[Feature] Declarative Addon Lifecycle (KEP-2.13)

Is there an existing issue for this?

• I have searched the existing issues (related: #6995, PR #6996 for addon-as-component)

What problem or limitation does this address?

KubeVela addons today are installed imperatively via vela addon enable and managed one version at a time, which creates several gaps:

• Imperative, one-shot install. vela addon enable runs once. The addon's owned Application drift-corrects its resources/ components, but definitions, Views, ConfigTemplates, and Schemas are applied as auxiliary outputs outside spec.components, so the Application controller has no knowledge of them and can't detect or heal out-of-band edits or deletes.
• No GitOps support. There's no CR that expresses "addon X at version Y should be installed," so platform teams can't declare addon state in git and have a controller reconcile toward it.
• No context-aware installation. Addon definitions can't gate themselves on cluster capabilities without custom wrapper tooling.
• Monolithic disable. vela addon disable removes everything immediately, with no way to defer removal until consuming Applications have migrated.
• Risky upgrades. A new addon version that changes a definition's parameter schema lands on every consumer immediately, with no migration window or warning.
• No composition model. Installing multiple related addons with version pinning requires manual coordination.

Without continuous reconciliation, the versioned X-Definition API model in KEP-2.20 (module identity, API line versioning) has no reliable delivery mechanism to enforce drift correction and deprecation.

Describe the solution you'd like

Introduce an Addon CR as the declarative, continuously-reconciled unit of addon delivery, wrapping the existing pkg/addon/ install/upgrade logic rather than replacing it. Key pieces:

• Addon CR (cluster-scoped): spec.version (exact tag = pinned mode, semver constraint = tracking mode), spec.upgradePolicy (Manual/Auto), spec.registry, spec.parameters, spec.clusters, spec.overrideDefinitions, spec.deletionPolicy (Protect/Force/Orphan).
• Reconciliation loop with strict three-tier ordering: owned Application must be healthy first, then a global definition-conflict pre-flight, then per-API-line auxiliary resources gated on kstatus readiness, then definitions last (the go-live signal).
• Stale resource cleanup on upgrade: hard-delete stale Views/ConfigTemplates/Schemas; leave definitions and auxiliary resources to the deprecation lifecycle (KEP-2.20) since Applications bind to them at runtime.
• Ownership model: the Application remains the structural owner (via ResourceTracker GC); the Addon CR's finalizer only gates when that Application gets deleted, per deletionPolicy.
• Addon-of-addons composition: a new built-in addon component type that renders an Addon CR, so a single Application can express dependency-ordered platform bundles (e.g. crossplane → crossplane-aws → postgres/aws-s3 → observability).
• CLI: vela addon enable/disable/upgrade/list/status become thin Addon CR writers/readers; add vela addon apply --local for testing an addon tree directly without a registry or CR.
• Backwards compatibility: an inheritance sweep reconstructs Addon CRs for pre-existing Applications installed by the old CLI, and definitions/ remains a permanent (not migration-only) authoring path alongside modules/.

Full design: design/vela-core/keps/2.13-addons

Alternatives considered

The KEP itself documents three unaccepted, in-progress design explorations under design/vela-core/keps/2.13-addons/design/ that revisit how much of this reconcile loop the addon controller needs to own, now that per-component topology placement (#7213) is implemented:

1. Per-component topology placement — could let all addon resources move inside the generated Application's spec.components, so the Application controller (not a bespoke addon loop) handles dispatch, drift correction, and staleness cleanup.
2. Application-managed resources — notes that X-Definitions are actually namespace-scoped, so a co-located Application could own them via ordinary owner references instead of direct SSA-apply outside the Application.
3. CueX components instead of CRs — explores whether addons/modules could render nested Applications directly via a CueX provider, removing the need for a dedicated Addon CR and controller altogether.

This KEP's CR-and-controller model is the accepted baseline for initial delivery; the explorations above are tracked separately and may supersede parts of this design before it's finalized.

Separately, a dedicated-CRD-with-controller approach was already weighed against a pure component-based approach in the original addon-as-component proposal (#6995) and rejected there in favor of what became this KEP's hybrid: a CR for GitOps-facing desired state, wrapping the existing Application as payload.

Update: in-progress implementation (draft PR #7360, tracked in sub-issue #7362) has actually landed on exploration 3 first: it renders the addon inline via a CueX provider and folds it into the parent Application's own components, with no Addon CR and no addon controller at all. That gets composition and drift correction for the addon-of-addons case with much less new machinery, but it doesn't provide independent version tracking/upgrade policy, a deletion policy, the three-tier health-gated apply ordering, or a staleness diff for the nested addon. Whether this supersedes the CR-and-controller baseline below, or the two are meant to coexist, is an open decision for maintainers; see #7362 for details.

Sub-issues

• #7362 — addon component type (CueX-rendered, no Addon CR): implements the addon-of-addons composition piece of this KEP, currently via draft PR #7360, using design exploration 3 rather than the Addon CR baseline described below.

Additional context

Cross-KEP references:

• KEP-2.20 — module identity, API line versioning, deprecation lifecycle (this KEP's delivery mechanism assumes KEP-2.20's versioned API contract)
• KEP-2.22 — multi-instance addons (instance field is reserved but deferred)
• KEP-2.19 — named topology groups (forward migration target for spec.clusters)
• KEP-2.6 — KubeVela Operator installs/drift-corrects the addon controller deployment

Implementation scope (pkg/addon/, pkg/controller/addon/, pkg/webhook/core.oam.dev/v1beta1/application/, references/cli/):

• Addon CR API types: extended AddonSpec/AddonStatus, conditions, phases
• Addon controller: three-tier reconcile ordering, Application health gate, definition conflict pre-flight
• Per-API-line auxiliary readiness gating (kstatus) and parallel line processing
• Version selection: pinned mode, tracking mode with Manual/Auto upgrade policy
• Stale resource cleanup (staleness diff) on upgrade
• Deletion policy + finalizer (Protect/Force/Orphan)
• addon built-in component type for addon-of-addons composition — in progress, see #7362 (PR #7360)
• CLI: vela addon enable/disable/upgrade/list/status, vela addon apply --local
• Backwards-compat inheritance sweep for pre-existing (CR-less) addon Applications
• RBAC guidance for Addon CR creation (Security Considerations section)

Tracking implementation: PR #7360 (see #7362)