K8s Addons

K8s Addons are catalog entries that let Kubernetes clusters subscribe to desired blocks and install them via the block rollout. Describes the layers, usage in the cluster detail view, version pins and enforcement.

K8s Addons

Cluster addons are catalog entries that allow the API to subscribe desired blocks to a Kubernetes cluster and install them via the normal block rollout. Introduced with API 0.32.0.

Layers

Layer Model Role
Catalogue CatalogueApp Mapping to the registry URL of the template block
Catalog K8sAddon Defaults, Jinja config template, scope, is_default, allow_multiple, order, enforcement
Catalog Config K8sAddonConfigRevision One editable Jinja template per addon version (otherwise fallback to the addon default)
Desired State K8sClusterAddonSubscription Subscription on the cluster; soft-delete; associated instance block (block_name)

No dedicated trigger BRC per addon: the cluster reconcile creates/updates the block and a BlockRolloutItem (managed_by=subscription).

Usage

The cluster detail view has an Addons tab:

  • Available / Subscribe — subscribe to an addon (empty version = latest)
  • Subscribed / Remove — remove the subscription (soft-delete → uninstall → cleanup)
  • Version pin as a text field; status from block.installed / installation_status

enforcement=required (default addons): opt-out is removed again during the default reconcile; deletion only by superusers.

allow_multiple=false (default): at most one active subscription per cluster (e.g. Cilium). allow_multiple=true: multiple instances, each with its own block_name.

Promote

An existing instance block can be turned into a subscription manually (action on the block, auto_subscribed=false). Workspace reconcile no longer creates silent subscriptions (Spec 715 auto-adopt is dead). Default addons (is_default) continue to create empty subscriptions; existing blocks are not adopted in the process. Subscribe in the Addons tab remains the create path for new installations.

Config

  1. Render the addon default_block_config_template and the subscription block_config_template as Jinja (context includes k8scluster, addon, subscription)
  2. Parse YAML, deep-merge (lists are replaced)
  3. Result → Block.config

Adoption (deprecated)

Silent adoption of matching workspace blocks during reconcile (Spec 715) has been removed. Existing blocks only via Promote. API/operator blocks are still not overwritten during CLI import.

Conditions (INFO)

Condition Meaning
K8S_ADDON_VERSION_BEHIND Pin is behind the platform latest
K8S_ADDON_RECOMMENDED_MISSING recommended addon is missing

They do not feed into the WARNING/CRITICAL object state.

Deprecated

The former JSON field K8sCluster.addons / the sync hot path are dead. New deployments run via subscriptions.

Related Topics