Feat/k0s download airgapped bundle

[OliverTrautvetter]

This pull request adds support for airgapped (offline) installations of k0s, including both CLI and internal logic changes to handle airgap image bundles. It introduces new flags and validation logic for airgapped installs, updates download and install flows to handle airgap bundles, and enhances tests to cover these scenarios.

Clickup

Important Context to the PR

• This change introduces a breaking change and for that I cleared it with relevant stakeholders upfront and added an explanation to the PR description. Breaking can e.g. mean that this new installer can not install older versions of Codesphere

Tested with Lima.

Cut the internet for the vm.

Run the install

oms install k0s --install-config install-config.yaml --airgapped \
    --version v1.31.14+k0s.0 --k0sctl-version v0.33.0 \
    --ssh-key-path ~/.ssh/airgap_k0s

Using cached k0s v1.31.14+k0s.0 at /home/.../.cache/oms/k0s
Using cached airgap bundle /home/.../.cache/oms/k0s-airgap-bundle-v1.31.14+k0s.0-amd64
Using cached k0sctl v0.33.0 at /home/.../.cache/oms/k0sctl
Generating k0sctl configuration from install-config...
Generated k0sctl configuration at oms-workdir/k0sctl-config-airgap.yaml
Applying k0sctl configuration to deploy k0s cluster...
...
k0s cluster deployed successfully!

$ ls -la /var/lib/k0s/images/
-rw-r--r-- 1 root root 318554624 k0s-airgap-bundle-v1.31.14+k0s.0-amd64

$ journalctl -u k0scontroller | grep -i "oci bundle"
msg="Loading OCI bundles directory"                          component=OCIBundleReconciler
msg="Loading OCI bundle /var/lib/k0s/images/k0s-airgap-bundle-v1.31.14+k0s.0-amd64"
msg="OCI bundle /var/lib/k0s/images/k0s-airgap-bundle-v1.31.14+k0s.0-amd64 loaded"

result

$ kubectl get nodes
NAME            STATUS   ROLES           VERSION
lima-lima-oms   Ready    control-plane   v1.31.14+k0s

$ kubectl get pods -A
NAMESPACE     NAME                                       READY   STATUS    RESTARTS
kube-system   calico-kube-controllers-595dc5cd59-jbxkm   1/1     Running   0
kube-system   calico-node-x8px5                          1/1     Running   0
kube-system   coredns-7c95449b8b-8jb7t                   1/1     Running   0
kube-system   konnectivity-agent-7kn7n                   1/1     Running   0
kube-system   kube-proxy-gtbff                           1/1     Running   0
kube-system   metrics-server-685645db96-hq7q5            1/1     Running   0

[Copilot]

Copilot review overview

🟡 Changes recommended

The critical partial-download cache issue and two moderate installation-flow issues must be resolved before approval.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Remove partial airgap bundle after failed download · New
• Avoid redundant airgap bundle download with local bundle · New

What changed in this PR

Adds airgapped k0s installation support, including bundle downloading, caching, upload configuration, CLI options, documentation, and tests.

Changes:

• Adds airgap bundle discovery, caching, and downloading.
• Uploads bundles to nodes and configures offline image handling.
• Adds CLI flags, validation, documentation, and test coverage.

Required fixes:

• Critical — internal/installer/airgap.go:60: Failed downloads leave partial files in the cache, which later runs may treat as valid bundles. Remove failed destinations or download atomically via a temporary file.
• Moderate — cli/cmd/k0s/install_k0s.go:244: A supplied local bundle still triggers release-bundle acquisition, breaking offline installs and causing duplicate downloads with --force. Let getAirgapBundlePath exclusively handle bundle acquisition.
• Moderate — cli/cmd/k0s/install_k0s.go:264: Relative bundle paths are resolved differently during validation and by k0sctl. Convert them to absolute paths before generating the configuration.

File	Description
internal/​installer/​mocks.go	Updates generated k0s manager mocks.
internal/​installer/​k0sctl.go	Refactors k0sctl cache handling.
internal/​installer/​k0sctl_config.go	Adds airgap bundle upload configuration.
internal/​installer/​k0sctl_config_test.go	Tests airgap k0sctl configuration.
internal/​installer/​k0s.go	Adds airgap-aware downloads.
internal/​installer/​k0s_test.go	Tests bundle resolution and caching.
internal/​installer/​k0s_config.go	Configures airgapped image pull behavior.
internal/​installer/​k0s_config_test.go	Tests airgap pull-policy generation.
internal/​installer/​download.go	Adds shared download and cache helpers.
internal/​installer/​airgap.go	Implements bundle discovery and caching.
docs/​oms_install_k0s.md	Documents airgapped installation options.
docs/​oms_download_k0s.md	Documents airgap bundle downloads.
cli/​cmd/​k0s/​k0s_suite_test.go	Adds the k0s CLI test suite.
cli/​cmd/​k0s/​install_k0s.go	Adds the airgapped installation flow and validation.
cli/​cmd/​k0s/​install_k0s_test.go	Tests airgapped installation scenarios.
cli/​cmd/​k0s/​install_k0s_integration_test.go	Updates installation integration tests.
cli/​cmd/​k0s/​download_k0s.go	Adds the airgapped download flag.
cli/​cmd/​k0s/​download_k0s_test.go	Tests airgap download behavior.

Files not reviewed (1)

• internal/installer/mocks.go: Generated file

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.