[deckhouse-cli] Plugins / d8 self-update with requirements check

cmd/d8/root.go

@@ -45,8 +45,9 @@ import (
 	mirror "github.com/deckhouse/deckhouse-cli/internal/mirror/cmd"
 	network "github.com/deckhouse/deckhouse-cli/internal/network"
 	packagecmd "github.com/deckhouse/deckhouse-cli/internal/packagecmd"
-	plugins "github.com/deckhouse/deckhouse-cli/internal/plugins/cmd"
-	"github.com/deckhouse/deckhouse-cli/internal/plugins/cmd/flags"
+	pluginscmd "github.com/deckhouse/deckhouse-cli/internal/plugins/cmd"
+	"github.com/deckhouse/deckhouse-cli/internal/plugins/flags"
+	selfupdatecmd "github.com/deckhouse/deckhouse-cli/internal/selfupdate/cmd"
 	status "github.com/deckhouse/deckhouse-cli/internal/status/cmd"
 	system "github.com/deckhouse/deckhouse-cli/internal/system/cmd"
 	"github.com/deckhouse/deckhouse-cli/internal/tools"
@@ -85,16 +86,11 @@ func NewRootCommand() *RootCommand {
 		},
 	}
 
-	envCliPath := os.Getenv("DECKHOUSE_CLI_PATH")
+	envCliPath := os.Getenv(flags.EnvPluginsDir)
 	if envCliPath != "" {
 		flags.DeckhousePluginsDir = envCliPath
 	}
 
-	envRegistryRepo := os.Getenv("DECKHOUSE_REGISTRY_REPO")
-	if envRegistryRepo != "" {
-		flags.SourceRegistryRepo = envRegistryRepo
-	}
-
 	rootCmd.registerCommands()
 	rootCmd.cmd.SetGlobalNormalizationFunc(cliflag.WordSepNormalizeFunc)
 
@@ -128,12 +124,14 @@ func (r *RootCommand) registerCommands() {
 	if os.Getenv("DECKHOUSE_PLUGINS_ENABLED") != "true" {
 		r.cmd.AddCommand(system.NewCommand())
 	} else {
-		r.cmd.AddCommand(plugins.NewPluginCommand(plugins.SystemPluginName, "Operate system options in DKP", []string{"s", "p", "platform"}, r.logger.Named("system-command")))
+		r.cmd.AddCommand(pluginscmd.NewPluginCommand(pluginscmd.SystemPluginName, "Operate system options in DKP", []string{"s", "p", "platform"}, r.logger.Named("system-command")))
 	}
 
 	r.cmd.AddCommand(packagecmd.NewCommand())
 
-	r.cmd.AddCommand(plugins.NewCommand(r.logger.Named("plugins-command")))
+	r.cmd.AddCommand(pluginscmd.NewCommand(r.logger.Named("plugins-command")))
+
+	r.cmd.AddCommand(selfupdatecmd.NewCommand(r.logger.Named("cli-command")))
 }
 
 func (r *RootCommand) Execute() error {

docs/mirror-pull-dry-run.md

@@ -13,16 +13,21 @@ The key distinction from a no-op:
 |------|-------------|---------|
 | Validate registry access | yes | yes |
 | Resolve versions / channels | yes | yes |
-| Pull installer to tmpDir | yes | **yes** (needed to read `images_digests.json`) |
+| Read installer `images_digests.json` (platform) | via OCI layout in tmpDir | **streamed from the registry** (no layout) |
+| Stage installer/security/module OCI layout dirs in tmpDir | yes (with blobs) | **scaffolding only** (no image blobs) |
 | Pull release-channel metadata | yes | yes |
 | Download platform/module/security blobs | yes | **no** |
 | Write `platform.tar`, `security.tar`, module tarballs | yes | **no** |
 | Write `deckhousereleases.yaml` | yes | **no** |
 | Compute GOST digests | yes | **no** |
 
-Installer OCI layouts land in `--tmp-dir` (or `<bundle-path>/.tmp`) so the tool can
-extract the built-in image digest list from `deckhouse/candi/images_digests.json`.  
-The **bundle directory** (first positional argument) remains empty.
+In dry-run the **platform** service streams the built-in image digest list
+(`images_tags.json` / `images_digests.json`) straight from the remote installer image,
+layer by layer, without writing an OCI layout. The `installer`, `security` and `modules`
+services still create their OCI layout directories under `--tmp-dir` (or
+`<bundle-path>/.tmp`), but in dry-run they pull no image blobs (only layout scaffolding),
+so `--tmp-dir` ends up non-empty while the **bundle directory** (first positional
+argument) remains empty.
 
 ---
 
@@ -51,18 +56,22 @@ Expected output (abbreviated):
 ```
 INFO  Skipped releases lookup as tag "v1.69.0" is specifically requested with --deckhouse-tag
 INFO  Deckhouse releases to pull: [1.69.0]
-INFO  ╔ Pull release channels and installers
-INFO  ║ [1 / 1] Pulling registry.deckhouse.io/deckhouse/install:v1.69.0
-INFO  ╚ Pull release channels and installers succeeded in …
-INFO  Extracting images digests from Deckhouse installer v1.69.0
+INFO  Searching for Deckhouse built-in modules digests
+INFO  [dry-run] Streaming installer metadata for v1.69.0 from registry
 INFO  Deckhouse digests found: 319
-INFO  Found 320 images
 INFO  [dry-run] Platform images that would be pulled:
-INFO    registry.deckhouse.io/deckhouse/fe@sha256:…
-INFO    registry.deckhouse.io/deckhouse/fe/release-channel:v1.69.0
+INFO    Deckhouse components: 319 images
+INFO      registry.deckhouse.io/deckhouse/fe@sha256:…
+INFO    Release channels: 1
+INFO      registry.deckhouse.io/deckhouse/fe/release-channel:v1.69.0
+INFO    Installer: 1
+INFO      registry.deckhouse.io/deckhouse/fe/install:v1.69.0
+INFO    Standalone installer: 1
+INFO    Total: 322 platform images
+INFO  [dry-run] Installer images that would be pulled:
 INFO    registry.deckhouse.io/deckhouse/fe/install:v1.69.0
   …
-INFO  [dry-run] Done. No images were downloaded.
+  No images were downloaded (dry-run).
 ```
 
 ### All components
@@ -134,7 +143,7 @@ go test ./internal/mirror/... -run 'TestDryRun' -v -timeout 120s
 # Pull-command level (flag registration, no bundle output, exit 0)
 go test ./internal/mirror/cmd/pull/ -run 'TestDryRun' -v
 
-# Platform service level (installer pulled to tmpDir, bundle stays empty)
+# Platform service level (digests streamed, no platform OCI layout, bundle stays empty)
 go test ./internal/mirror/platform/ -run 'TestDryRun' -v
 ```
 
@@ -148,7 +157,8 @@ go test ./internal/mirror/platform/ -run 'TestDryRun' -v
 | `TestDryRunWithDeckhouseTag` | specific `--deckhouse-tag` works in dry-run |
 | `TestDryRunExitsZeroOnSuccess` | `Execute()` returns `nil` |
 | `TestDryRun_NoBundleFilesWritten` | platform service: bundleDir empty |
-| `TestDryRun_InstallerPulledToTmpDir` | platform service: `<tmpDir>/platform/install/` exists |
+| `TestDryRun_NoOCILayoutCreated` | platform service: `<tmpDir>/platform/install/` is **not** created (digests are streamed) |
+| `TestDryRun_WorkingDirHasLayouts` | installer / security service: OCI layout dir staged in workingDir, bundleDir empty |
 
 ### Integration smoke test (real registry)
 
@@ -171,20 +181,22 @@ D8_TEST_LICENSE_TOKEN=<token> \
 
 The test asserts:
 1. `Execute()` returns `nil`
-2. The bundle directory is **empty** — no `.tar` output
-3. The tmp directory is **non-empty** — OCI layouts were written (installer pull), proving
-   `images_digests.json` extraction was attempted
+2. The bundle directory has no `.tar` / `.chunk` output
+3. The tmp directory is **non-empty** - the `installer`, `security` and `modules` services
+   stage OCI layout scaffolding there (no image blobs); the platform digest list itself is
+   streamed from the registry, not staged
 
 Sample passing output:
 
 ```
 === RUN   TestDryRunRealRegistry
 …
 INFO  Deckhouse digests found: 319
-INFO  Found 320 images
 INFO  [dry-run] Platform images that would be pulled:
-INFO    registry.deckhouse.io/deckhouse/fe@sha256:e927fc9…
-  … 320 lines …
+INFO    Deckhouse components: 319 images
+INFO      registry.deckhouse.io/deckhouse/fe@sha256:e927fc9…
+INFO    Total: 322 platform images
+  … more dry-run plans for installer / security / modules …
     pull_realregistry_test.go:94: tmpDir files written during dry-run: 51
     pull_realregistry_test.go:95: bundleDir entries (must be 0): 0
 --- PASS: TestDryRunRealRegistry (79.99s)
@@ -203,13 +215,12 @@ Puller.Execute()
             │    ├─ findTagsToMirror()                    ← real network call
             │    ├─ downloadList.FillDeckhouseImages()    ← in-memory
             │    └─ pullDeckhousePlatform()
-            │         ├─ pullDeckhouseReleaseChannels()   ← writes to tmpDir
-            │         ├─ pullInstallers()                 ← writes to tmpDir ← KEY STEP
-            │         ├─ pullStandaloneInstallers()       ← writes to tmpDir
-            │         │   (pullDeckhouseImages SKIPPED in dry-run)
-            │         ├─ ExtractImageDigestsFromInstaller ← reads images_digests.json
-            │         └─ [dry-run guard] print plan → return nil
-            │              (no platform.tar written)
+            │         └─ [DryRun] pullDeckhousePlatformDryRun()
+            │              ├─ extractImageDigestsFromRemote()  ← streams images_tags.json /
+            │              │      images_digests.json from the remote image (no OCI layout)
+            │              └─ print plan → return nil
+            │            (pullDeckhouseReleaseChannels / pullInstallers /
+            │             pullStandaloneInstallers / pullDeckhouseImages all SKIPPED)
             ├─ installer.Service.PullInstaller()         [DryRun=true]
             │    ├─ validateInstallerAccess()
             │    ├─ findTagsToMirror()
@@ -225,25 +236,26 @@ Puller.Execute()
                  └─ [dry-run guard] print plan → return nil
 
   After Pull() returns:
-    if DryRun → print "[dry-run] Done." → return nil
+    if DryRun → print summary "No images were downloaded (dry-run)." → return nil
     else      → computeGOSTDigests, finalCleanup
 ```
 
-The installer image **is** pulled to `tmpDir` in dry-run mode because
-`images_digests.json` inside it is the only source for the ~300 component image
-digest references that the platform bundle would contain. Without this step,
-dry-run could only report the 5–10 top-level image tags, missing the vast majority
-of what a real pull actually downloads.
+The platform service reads `images_digests.json` (or `images_tags.json`) **without**
+pulling the installer to `tmpDir`: `extractImageDigestsFromRemote` streams just the layer
+containing that file straight from the registry. It is the only source for the ~300
+component image digest references that the platform bundle would contain - without it,
+dry-run could only report the 5-10 top-level image tags, missing the vast majority of
+what a real pull actually downloads.
 
 ---
 
 ## Temporary files
 
 | Location | Created in dry-run? | Description |
 |----------|---------------------|-------------|
-| `<tmpDir>/platform/install/` | **yes** | Installer OCI layout |
-| `<tmpDir>/platform/install-standalone/` | **yes** | Standalone installer OCI layout |
-| `<tmpDir>/platform/release/` | **yes** | Release-channel metadata OCI layout |
+| `<tmpDir>/platform/...` | **no** | Platform digests are streamed; no platform OCI layout is written |
+| `<tmpDir>/installer/` | **yes** | Installer OCI layout dir (scaffolding only, no blobs) |
+| `<tmpDir>/security*/`, `<tmpDir>/modules*/` | **yes** | Security / module OCI layout dirs (scaffolding only, no blobs) |
 | `<bundleDir>/platform.tar` | no | Not created |
 | `<bundleDir>/security.tar` | no | Not created |
 | `<bundleDir>/modules-*.tar` | no | Not created |

docs/plugins.md

@@ -0,0 +1,117 @@
+# d8 Plugins (`d8 plugins`)
+
+Plugins are versioned binaries distributed through the cluster registry.
+`d8` installs, updates, and removes them for you.
+
+**Contents:** [Source](#plugin-source) · [Commands](#commands) ·
+[Versions & majors](#versions-majors-and-switching) ·
+[Requirements](#requirements) ·
+[Flags & env](#flags-and-environment-variables) ·
+[Troubleshooting](#troubleshooting)
+
+> [!NOTE]
+> The `d8 plugins` command group is hidden from the root `--help` while the
+> plugin ecosystem rolls out. The commands below are fully functional.
+
+## Plugin source
+
+Plugins are pulled from the in-cluster **registry-packages-proxy**, the same
+channel as d8 self-update. There is no direct-registry path: every `d8 plugins`
+command reaches the registry through the proxy, so a reachable cluster is
+required. The access model:
+
+- Authentication: the **Bearer token** from your kubeconfig (client
+  certificates do not work).
+- Authorization: the ClusterRole `d8:registry-packages-proxy:cli-download`,
+  bound by the cluster administrator.
+- Endpoint: discovered automatically; override with `--rpp-endpoint` /
+  `D8_RPP_ENDPOINT`, pass a private CA with `--rpp-ca-file`.
+
+See [self-update.md - How access works](self-update.md#how-access-works) for
+the full picture (RBAC binding example, OIDC kubeconfig, endpoint discovery).
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `d8 plugins versions <name>` | lists all published versions of one plugin |
+| `d8 plugins install <name>` | installs the newest version compatible with your cluster |
+| `d8 plugins install <name> --version X` | installs an exact version |
+| `d8 plugins install <name> --use-major N` | switches majors explicitly |
+| `d8 plugins update <name>` / `update all` | updates within the current major |
+| `d8 plugins list` | shows installed plugins (the proxy serves no catalog, so available plugins are not listed) |
+| `d8 plugins contract <name>` | shows a plugin's contract: version, description, requirements |
+| `d8 plugins remove <name>` / `remove all` | removes plugins |
+
+```console
+$ d8 plugins versions package
+  v0.1.2   newer
+* v0.0.21  current
+  v0.0.20
+
+$ d8 plugins install package
+Installing plugin: package
+Tag: v0.0.21
+...
+✓ Plugin 'package' successfully installed!
+```
+
+## Versions, majors and switching
+
+Plugins are stored per major version, with a `current` symlink selecting the
+active one:
+
+```
+/opt/deckhouse/lib/deckhouse-cli/plugins/<name>/v<major>/
+```
+
+Rules that follow from this layout:
+
+- `d8 plugins update` stays **within the installed major**. Crossing majors is
+  always an explicit decision: `--use-major N` or `--version X`.
+- Installing a version that is already on disk just repoints the symlink - no
+  download.
+- Installing the active version says so and does nothing; `--force`
+  re-downloads.
+- No root access to `/opt/deckhouse/lib`? Plugins go to `~/.deckhouse-cli`
+  automatically.
+
+## Requirements
+
+A plugin's contract may declare requirements:
+
+- other plugins;
+- Kubernetes / Deckhouse versions;
+- enabled modules.
+
+They are validated **before** anything is downloaded or switched:
+
+```console
+$ d8 plugins install package
+...
+Error: plugin requirements not satisfied      # e.g. requires plugin delivery-kit
+```
+
+Plugins this one depends on are installed/upgraded automatically.
+
+- `--skip-cluster-checks` (or `D8_PLUGINS_SKIP_CLUSTER_CHECKS=1`) - skip
+  cluster-side checks, e.g. in air-gapped scenarios.
+
+## Flags and environment variables
+
+| Flag | Env | Purpose |
+|---|---|---|
+| `--kubeconfig`, `-k` / `--context` | `KUBECONFIG` | cluster identity (the Bearer token source) |
+| `--plugins-dir` | `DECKHOUSE_CLI_PATH` | plugins directory |
+| `--skip-cluster-checks` | `D8_PLUGINS_SKIP_CLUSTER_CHECKS=1` | skip cluster-side requirement checks |
+| `--rpp-endpoint` | `D8_RPP_ENDPOINT` | proxy base URL; discovered from the cluster when empty |
+| `--rpp-ca-file` | `D8_RPP_CA_FILE` | PEM CA bundle to verify the proxy TLS certificate |
+| `--rpp-insecure-skip-tls-verify` | - | skip proxy TLS verification (debugging only) |
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `image or tag not found` (404) on a plugin | the plugin is not published in this cluster's registry | check with `d8 plugins versions <name>`; publishing is the plugin CI's job |
+| `plugin requirements not satisfied` | the contract requires other plugins or cluster versions/modules | see `d8 plugins contract <name>`; plugin deps are auto-installed, cluster requirements are not |
+| 401 / 403 / `x509: ...` reaching the proxy | access or TLS issue with the registry-packages-proxy | see [self-update.md - Troubleshooting](self-update.md#troubleshooting) - the access model is shared |