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 plugins cobra commands are a thin layer on top of it in internal/plugins/cmd (package pluginscmd), one file per command - the same split internal/selfupdate / internal/selfupdate/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

Plugin source

rppPluginSource (rpp_source.go) implements the PluginSource interface (source.go) and is the only source: plugins are pulled through the in-cluster registry-packages-proxy using the kubeconfig identity, with no registry credentials on the user side (ADR: 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; the plugin routes are /v1/images/deckhouse-cli/plugins/<name>/....

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, modules incl. mandatory/conditional/anyOf): verified against a one-shot cluster snapshot (the requirements/ package); the cluster is queried only when the plugin actually declares such requirements, so contract-less plugins install offline.
• 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.
• At runtime: the wrapper re-validates requirements before EVERY plugin run (the gate is skipped for purely local queries: --help, --version, completion).
• 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

Boundaries and deliberate decisions

• Listing the full plugin catalog over RPP is not supported (the proxy has no catalog endpoint); install/update by name works.
• 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.

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).