Documentation / Administer
Administer · v0.0.1 Registry & air gap Mirror signed, digest-pinned releases and add-on artifacts into a customer registry without silent public fallback.
Audience Registry administrators, security and platform teamsReading time 18 minCommands in context 13 guided stepsReviewed source fcc5871 · 30 July 2026
RC Exact release scope. This page documents the reviewed v0.0.1 source at fcc5871. Check release status before enabling a gated capability.
Distribution modes Mode Source of artifacts Required evidence Online Approved public registries and release bundle. Signatures, checksums, digests, compatibility, outbound policy. Private registry Mirrored API, agent, tools, add-ons, and metadata. Promotion record, digest equality, registry trust/auth, pull tests. Air-gapped Preassembled signed bundle imported through a controlled transfer. Complete inventory, transfer chain, offline verification, no-egress test.
Immutable artifact contract ✓ API and agent image references include an immutable sha256 digest.
✓ Official runtime subject basenames remain clusterpilot-api and clusterpilot-agent.
✓ Charts, manifests, tools, and add-on images have complete lock metadata.
✓ Signed release metadata and compatibility inputs remain available after mirroring.
✓ The target environment refuses tag-only, missing, stale, partially synchronized, or drifted mirrors.
✓ There is no undocumented fallback to latest, an alternate registry, or the public internet.
Commands for this step Generate the signed compatibility contract Release engineering binds supported versions and runtime artifacts to a signed compatibility manifest before distribution.
Protected workflow Run only on an approved maintainer, security, or release system.
01
Privileged PowerShell
Generate and sign the compatibility manifest Materialize the release, component, agent and database compatibility contract and sign it with the protected release key.
Before you run it Approved release identity and compatibility bounds Protected signing context Repository template PowerShell · release-compatibility-manifest Copy
& ./scripts/generate-compatibility-manifest.ps1 `
-RepositoryRoot (Resolve-Path .).Path `
-TemplatePath ./release/compatibility-manifest.template.json `
-OutputPath ./artifacts/compatibility-manifest.json `
-SignaturePath ./artifacts/compatibility-manifest.json.sig `
-SigningPrivateKeyPath "<protected-signing-private-key>" `
-SigningKeyId "<release-signing-key-id>" `
-ReleaseVersion <release-version> `
-PublishedAtUtc <iso-8601-utc> `
-BackendVersion <backend-version> `
-FrontendVersion <frontend-version> `
-AgentVersion <agent-version> `
-MinDbMigration <minimum-migration> `
-MaxDbMigration <maximum-migration> `
-RequiredDeprecationComponents <comma-separated-components>✓ Expected result Canonical manifest and detached signature bind every supported version and database floor/ceiling.
Reviewed source scripts/generate-compatibility-manifest.ps1Harbor integration Use a dedicated project and a least-privileged robot account for ClusterPilot promotion/pull workflows. Retain the robot credential through a typed SecretRef and validate Harbor TLS, project quota, retention, scanning, garbage collection, and replication policy.
Harbor robot account guidance↗ Harbor vulnerability scanning↗ Scanning is a separate decision A Harbor scan result complements—but does not replace—release signature, SBOM, provenance, digest lock, and customer vulnerability policy.
Commands for this step Prepare, mirror, resolve, and promote add-on artifacts Always review the dry-run result before an apply step. Promotion requires the exact lock and approved Harbor destination.
Protected workflow Run only on an approved maintainer, security, or release system.
01
Changes state PowerShell
Prepare the add-on image mirror plan Resolve the approved add-on inventory into immutable target-registry mappings for disconnected distribution.
Before you run it Reviewed digest-pinned add-on inventory Approved target registry/project convention PowerShell · release-addon-image-pack-prepare Copy
& ./scripts/prepare-addon-image-pack.ps1 `
-InventoryPath ./release/addons/image-inventory.json `
-TargetRegistry harbor.example.com `
-TargetProjectPrefix clusterpilot-addons `
-OutputPath ./artifacts/addons/mirror-plan.json✓ Expected result A deterministic mirror plan maps every source digest to its governed target reference.
Reviewed source scripts/prepare-addon-image-pack.ps102
Changes state PowerShell
Compose the canonical add-on image lock Merge one or more image-lock documents and an optional artifact lock into a single deterministic release lock.
Before you run it Verified source image locks Optional artifact lock verified against the same release PowerShell · release-addon-lock-compose Copy
& ./scripts/compose-addon-image-lock.ps1 `
-ImageLockPath @('./artifacts/addons/core.image-lock.json','./artifacts/addons/optional.image-lock.json') `
-ArtifactLockPath ./artifacts/addons/artifact-lock.json `
-OutputPath ./artifacts/addons/addon-image-lock.json `
-GeneratedAtUtc (Get-Date).ToUniversalTime().ToString("o") `
-Source clusterpilot-composed-addon-image-lock✓ Expected result The output contains stable, conflict-free digest locks and source identity.
Reviewed source scripts/compose-addon-image-lock.ps103
Read-only PowerShell
Dry-run add-on image mirroring Validate all source/target mappings and tool commands without copying images.
Before you run it Verified mirror plan Selected mirror tool installed Target naming reviewed PowerShell · release-addon-mirror-dry-run Copy
& ./scripts/mirror-addon-images.ps1 `
-MirrorPlanPath ./artifacts/addons/mirror-plan.json `
-Tool crane `
-ToolPath crane `
-DockerPath docker `
-OutputPath ./artifacts/addons/mirror-dry-run.json `
-GeneratedAtUtc (Get-Date).ToUniversalTime().ToString("o") `
-DryRun✓ Expected result Every planned copy is reported with no registry mutation.
Reviewed source scripts/mirror-addon-images.ps104
Privileged PowerShell
Mirror add-on images Copy every digest-pinned add-on image to the approved registry and record the result.
Before you run it Successful dry-run Authenticated scoped registry write access Approved egress/mirror window PowerShell · release-addon-mirror-apply Copy
& ./scripts/mirror-addon-images.ps1 `
-MirrorPlanPath ./artifacts/addons/mirror-plan.json `
-Tool crane `
-ToolPath crane `
-DockerPath docker `
-OutputPath ./artifacts/addons/mirror-result.json `
-GeneratedAtUtc (Get-Date).ToUniversalTime().ToString("o")✓ Expected result Each immutable source digest exists at its planned target and the result document records success.
Reviewed source scripts/mirror-addon-images.ps105
Changes state PowerShell
Resolve an add-on pack from the registry Inspect the mirrored registry state and produce the resolved add-on pack evidence.
Before you run it Completed add-on mirror Registry read access Docker CLI PowerShell · release-addon-pack-resolve Copy
& ./scripts/resolve-addon-image-pack-from-registry.ps1 `
-MirrorPlanPath ./artifacts/addons/mirror-plan.json `
-OutputPath ./artifacts/addons/resolved-pack.json `
-DockerPath docker `
-GeneratedAtUtc (Get-Date).ToUniversalTime().ToString("o")✓ Expected result Every planned target resolves to the expected immutable digest.
Reviewed source scripts/resolve-addon-image-pack-from-registry.ps106
Read-only PowerShell
Dry-run add-on artifact promotion Validate ORAS and Helm promotion commands for the approved add-on plan without publishing artifacts.
Before you run it Verified mirror plan ORAS and Helm installed Target registry/repository reviewed PowerShell · release-addon-promote-dry-run Copy
& ./scripts/promote-addon-artifacts.ps1 `
-MirrorPlanPath ./artifacts/addons/mirror-plan.json `
-OutputPath ./artifacts/addons/promotion-dry-run.json `
-OrasPath oras `
-HelmPath helm `
-GeneratedAtUtc (Get-Date).ToUniversalTime().ToString("o") `
-DryRun✓ Expected result All intended promotions are reported and no artifact is pushed.
Reviewed source scripts/promote-addon-artifacts.ps107
Privileged PowerShell
Promote add-on artifacts Publish governed add-on OCI/Helm artifacts according to the approved mirror plan.
Before you run it Successful promotion dry-run Scoped ORAS/Helm registry write access Approval for target repositories PowerShell · release-addon-promote-apply Copy
& ./scripts/promote-addon-artifacts.ps1 `
-MirrorPlanPath ./artifacts/addons/mirror-plan.json `
-OutputPath ./artifacts/addons/promotion-result.json `
-OrasPath oras `
-HelmPath helm `
-GeneratedAtUtc (Get-Date).ToUniversalTime().ToString("o")✓ Expected result Every planned artifact is promoted and the result document binds target identity and time.
Reviewed source scripts/promote-addon-artifacts.ps1Air-gap rollout 01 Generate the complete inventory Include API, agent, tools, Kubernetes artifacts, CNI, add-ons, charts/manifests, metadata, signatures, SBOM, and provenance.
02 Verify before export Validate signatures and checksums in the connected staging environment.
03 Transfer under customer policy Record bundle identity, media/courier control, approver, and destination.
04 Verify after import Recompute checksums, validate signatures offline, and compare the inventory.
05 Promote to the private registry Preserve original digests and record target references and registry evidence.
06 Test no-egress operation Block external DNS/egress and prove install, agent heartbeat, cluster lifecycle, add-on, validation, backup, and recovery paths.
Commands for this step Prepare and promote offline cluster and runtime images Use the signed release locks, verify the disconnected destination, and never skip the dry-run before mirroring or promotion.
Protected workflow Run only on an approved maintainer, security, or release system.
01
Changes state PowerShell
Prepare a Kubernetes cluster-build image pack Resolve Kubernetes release images into a digest-pinned mirror plan for the approved target registry.
Before you run it Supported Kubernetes version Reviewed image list or trusted kubeadm output Approved target registry PowerShell · release-cluster-build-pack-prepare Copy
& ./scripts/prepare-cluster-build-image-pack.ps1 `
-KubernetesVersion <supported-kubernetes-version> `
-TargetRegistry harbor.example.com `
-TargetProject clusterpilot-kubernetes `
-OutputPath ./artifacts/cluster-build/mirror-plan.json `
-ImageListPath ./release/kubernetes/images.txt `
-KubeadmPath kubeadm `
-SourceImageRepository registry.k8s.io✓ Expected result A complete source-to-target image plan is written for the selected Kubernetes version.
Reviewed source scripts/prepare-cluster-build-image-pack.ps102
Read-only PowerShell
Dry-run Kubernetes build image mirroring Validate all Kubernetes build-image mirror commands without registry mutation.
Before you run it Verified cluster-build mirror plan Crane or Skopeo installed PowerShell · release-cluster-build-mirror-dry-run Copy
& ./scripts/mirror-cluster-build-images.ps1 `
-MirrorPlanPath ./artifacts/cluster-build/mirror-plan.json `
-Tool crane `
-ToolPath crane `
-OutputPath ./artifacts/cluster-build/mirror-dry-run.json `
-GeneratedAtUtc (Get-Date).ToUniversalTime().ToString("o") `
-DryRun✓ Expected result Every source/target copy is resolved without changing the registry.
Reviewed source scripts/mirror-cluster-build-images.ps103
Privileged PowerShell
Mirror Kubernetes build images Copy the approved Kubernetes build images into the target registry and record immutable results.
Before you run it Successful dry-run Scoped registry write access Approved Kubernetes version and target project PowerShell · release-cluster-build-mirror-apply Copy
& ./scripts/mirror-cluster-build-images.ps1 `
-MirrorPlanPath ./artifacts/cluster-build/mirror-plan.json `
-Tool crane `
-ToolPath crane `
-OutputPath ./artifacts/cluster-build/mirror-result.json `
-GeneratedAtUtc (Get-Date).ToUniversalTime().ToString("o")✓ Expected result Every target image resolves to the planned digest.
Reviewed source scripts/mirror-cluster-build-images.ps104
Read-only PowerShell
Dry-run runtime image promotion Validate API/agent runtime promotion commands without copying images.
Before you run it Signed runtime image inventory Crane installed Target registry naming approved PowerShell · release-runtime-promote-dry-run Copy
& ./scripts/promote-runtime-images.ps1 `
-RuntimeImagesPath ./artifacts/release/runtime-images.json `
-TargetRegistry harbor.example.com `
-TargetProject clusterpilot-runtime `
-ToolPath crane `
-OutputPath ./artifacts/release/runtime-promotion-dry-run.json `
-GeneratedAtUtc (Get-Date).ToUniversalTime().ToString("o") `
-DryRun✓ Expected result All immutable runtime mappings are reported without registry mutation.
Reviewed source scripts/promote-runtime-images.ps105
Privileged PowerShell
Promote runtime images Copy signed API/agent runtime digests into the approved registry namespace.
Before you run it Successful dry-run Scoped registry write access Verified signed runtime inventory PowerShell · release-runtime-promote-apply Copy
& ./scripts/promote-runtime-images.ps1 `
-RuntimeImagesPath ./artifacts/release/runtime-images.json `
-TargetRegistry harbor.example.com `
-TargetProject clusterpilot-runtime `
-ToolPath crane `
-OutputPath ./artifacts/release/runtime-promotion-result.json `
-GeneratedAtUtc (Get-Date).ToUniversalTime().ToString("o")✓ Expected result Promoted API and agent targets retain their exact signed source digests.
Reviewed source scripts/promote-runtime-images.ps1v0.0.1 release boundary Self-hosted and air-gap distribution are production-gated in v0.0.1. The release-readiness line still requires complete real registry, private-CA, no-egress, failure-injection, restart, cleanup, and promotion evidence before a broad production claim.
Review open maturity limits → 