plugins

d8 plugins

The internal/plugins package manages d8 plugins: standalone binaries published to an OCI registry that d8 installs, updates, and runs as if they were native subcommands. The machinery lives in this package (the Manager); the d8 dist plugins cobra commands are a thin layer on top of it in internal/plugins/cmd (package pluginscmd), one file per command, mounted as a subtree of d8 dist (internal/dist/cmd) - the same machinery/commands split internal/selfupdate / internal/dist/cmd uses.

Why

• Isolate dependencies and let teams develop plugins independently of d8.
• Keep d8 itself compact - heavy functionality ships as plugins.
• Guarantee compatibility: a plugin declares requirements (Kubernetes, Deckhouse, modules, other plugins) and d8 enforces them both at install time and before every run.

Commands

Overriding a built-in command

A handful of top-level commands are overridable: delivery-kit, data, snapshot, iam, network, v, stronghold, package and system. Install a plugin named exactly like one of them and it takes the command over; with no such plugin installed, the built-in implementation serves it. The table lives in overridableCommands (cmd/d8/root.go).

Details worth knowing:

• Already-installed only. The override never reaches the registry: a plugin that exists upstream but is not installed locally does not displace a built-in, so d8 starts with no network access and no surprises. Auto-install on first use therefore applies only to plugins that are not shadowing a built-in.
• Canonical names only. A plugin must match the command's own name, never one of its aliases - there is no dk plugin, only delivery-kit. The built-in's aliases carry over to the wrapper, so d8 dk and d8 s keep working after an override.
• Resolved before flag parsing. Which commands get registered is decided at startup, so --plugins-dir cannot influence it; only the DECKHOUSE_CLI_PATH env var can. Both the configured root and the ~/.deckhouse-cli fallback are searched.
• Dependency bookkeeping. delivery-kit and package satisfy a plugin's dependency on that name while they ship as built-ins. Once a plugin takes one over, the name drops off that list and the dependency resolves against the real plugin, version constraints included.

Transports

Plugins reach the registry over one of two transports, chosen in InitPluginServices (init.go) by whether the hidden --source flag is set. Both implement pluginSource (source.go) and report which one they are via Transport(), so a message can name the transport instead of leaving it implicit.

They differ in one capability, expressed as the separate pluginCatalog interface:

Enumeration is a property of the transport, not a runtime failure. The catalog is the tag list of the deckhouse-cli/plugins repository, and the proxy allowlist (isAllowedCLIImagePath in the Deckhouse repo) admits only deckhouse-cli and deckhouse-cli/plugins/<name>, explicitly refusing the bare deckhouse-cli/plugins path. So rppPluginSource does not implement pluginCatalog and never issues the request; AvailablePlugins returns ErrCatalogUnsupported naming the transport, and d8 dist plugins list prints its installed half as usual.

• rppPluginSource (rpp_source.go) - TransportRPP, the default and only supported source. Plugins are pulled through the in-cluster registry-packages-proxy using the kubeconfig identity, with no registry credentials on the user side (ADR #386: deckhouse-cli reaches the registry exclusively through the proxy, so every command needs a reachable cluster). See internal/selfupdate/README.md for what RPP is and how authorization works - plugin download is gated by the same d8:registry-packages-proxy:cli-download ClusterRole as self-update, because both travel the /v1/images/ route. The plugin routes are /v1/images/deckhouse-cli/plugins/<name>/{tags,manifests/<ref>,images/<version>}.
• registryPluginSource (source_legacy.go) - TransportRegistry, a temporary, hidden --source bypass. It pulls straight from a registry repo with go-containerregistry, skipping the proxy and the cluster, and force-sets --skip-cluster-checks. It exists for pre-#386 workflows and is documented for removal (grep marker legacy --source).

What a plugin image contains

• plugin - the executable, in the image layers;
• the contract - name, version, description, requested env vars, flags, and requirements (Kubernetes / Deckhouse / modules / plugins) - published as a base64-JSON contract annotation on the image manifest.

The RPP source fetches the raw image manifest over the proxy manifests/<ref> route (a single manifest fetch, no layer pull) and reads the contract from its base64-JSON contract annotation itself. The binary is pulled separately (full image, over the images/<version> route) only when a plugin is installed.

On-disk layout

<plugins-dir>/                       # /opt/deckhouse/lib/deckhouse-cli by default
├── plugins/<name>/
│   ├── v<major>/<name>             # one binary per major version
│   ├── current -> v<major>/<name>  # the active version (atomic symlink swap)
│   └── install.lock                # one install lock per plugin
└── cache/contracts/<name>.json     # contract of the installed version (atomic writes)

• --plugins-dir / DECKHOUSE_CLI_PATH override the root; if it is not writable, installs fall back to ~/.deckhouse-cli.
• "Installed" means "has a current symlink" - a leftover directory from a failed install is never treated as an installed plugin.

How install works (InstallPlugin)

1. Validate the plugin name (a single OCI path component - nothing else may reach filesystem paths or registry routes).
2. Pick the version (see policy below) and take the per-plugin lock.
3. If the selected version is already current - nothing to do (--force re-pulls).
4. Fetch the contract and validate ALL requirements BEFORE any switch - including the fast path that merely repoints current to an already installed version.
5. Download into a staged file (<binary>.new) - the live binary keeps working for the whole download.
6. Smoke-test the staged binary (--version, fallback version; only a clean exit is required) - a corrupt or wrong-platform artifact is rejected before it replaces anything.
7. Atomically swap the new binary in (rename over the live one - the original is untouched on failure), write the contract cache, then atomically repoint current.

A failure at any step leaves the previous version installed and working.

Version selection policy

• Default pick: the newest stable semver tag whose cluster-side requirements are satisfied AND whose plugin->plugin dependency chain is resolvable - versions are probed newest to oldest and the first that passes both wins (a too-new release, or one whose dependencies cannot be satisfied, does not block updates).
• Updates stay within the installed major; crossing majors requires an explicit --use-major N. The major is read from disk (the current symlink), so a broken binary cannot drop the pin.
• Downgrade guard: the implicit path never installs a version older than the installed one - e.g. when the newest tag's contract is temporarily unreadable. Downgrades are explicit only (--version, --use-major).
• Pre-releases (rc/alpha/beta) are never picked by default; install them via --version.
• An unreachable cluster or a malformed contract is a hard error, not a silent fallback to an older version.

Requirements enforcement

• Cluster-side (kubernetes, deckhouse, and modules - mandatory/conditional/anyOf/noneOf, the last forbidding a module): verified against a one-shot cluster snapshot (the requirements/ package) built from three reads - the API-server version, the deckhouse deployment's core.deckhouse.io/version annotation, and a modules.deckhouse.io list. The snapshot is lazy (built only when the plugin declares such requirements, so contract-less plugins install offline), cached once per run, and bounded by a 30s probe timeout. A non-release Deckhouse version (e.g. dev) skips the Deckhouse check with a warning rather than failing.
• Plugin-to-plugin: a plugin's mandatory dependencies are installed and upgraded automatically (the resolution planner: constraint-aware, newest satisfying version, within each dependency's own major - or across it when --use-major cascades). Conflicts with already-installed plugins skip a candidate during selection. Conditional dependencies are enforced only when that plugin is already installed and are never auto-installed.
• At runtime: the wrapper re-validates requirements before EVERY plugin run. The gate is skipped for local-only invocations - --help/-h (anywhere before a --), --version/-v or help/completion as the first arg, and cobra's __complete* requests - and when the plugin ships no contract.
• Escape hatch for air-gapped setups: --skip-cluster-checks / D8_PLUGINS_SKIP_CLUSTER_CHECKS=1 (downgrades the check to a warning).

Running a plugin (the wrapper)

• All arguments are forwarded verbatim (the wrapper parses no flags itself).
• Env requested by the contract is injected: KUBECONFIG (the path d8 uses) and PLUGINS_CALLER (the d8 executable); everything else passes through.
• stdin/stdout/stderr are inherited; the plugin's exact exit code is propagated.
• On d8's own termination the plugin gets SIGTERM and a grace period, not an instant SIGKILL.

Switches

Air-gapped delivery

d8 mirror pull mirrors plugins into the images bundle automatically (plugins whose contracts name the mirrored modules, plus their mandatory plugin dependencies; --include-plugin adds more). After d8 mirror push the target registry holds them at deckhouse-cli/plugins/<name>, where the proxy serves them - install/update work as usual. See internal/mirror/README.MD (Plugin Mirroring).

Boundaries and deliberate decisions

• Enumerating the published plugins works only over TransportRegistry; the proxy allowlist refuses the plugins-repository path, so list reports that half as unsupported and still prints the installed half. See Transports above.
• Idempotency compares the version reported by the binary itself; a plugin that prints a non-semver banner is re-pulled on every explicit update.
• Dependency resolution is dry-run during selection (a candidate whose chain cannot be resolved is skipped); the chain is actually installed only for the finally chosen version. Recursion has a cycle guard and a depth cap.
• Dependencies are only upgraded, never downgraded, to satisfy a constraint.
• A plugin contract may depend on external modules only (those served from deckhouse/<edition>/modules/<name>), never on modules embedded in the platform image: d8 mirror auto-selects plugins from the mirrored external modules alone, so an embedded-module requirement never triggers selection and, as a secondary requirement, gets the plugin skipped as "not in the bundle".

Package map

Related: internal/rpp (proxy HTTP client), internal/lockfile (install lock), internal/selfupdate (the same store-and-symlink update pattern for the d8 binary itself).