Add native airgap bundle support by kke · Pull Request #1080 · k0sproject/k0sctl

kke · 2026-05-07T10:01:08Z

Add native handling for k0s airgap bundles under spec.k0s.airgap so users do not need to model the official bundle upload manually with spec.hosts[*].files.

This MVP adds:

schema, defaults, and validation for enabled, source, mode, path, url, and sha256
support for source: auto, source: local, and source: url in upload mode
official release bundle resolution from spec.k0s.version
local XDG cache storage and per-platform download deduplication
SHA-256 validation for local and custom URL sources
Linux worker-capable host planning for worker, controller+worker, and single roles
upload of bundles to /images before worker install or upgrade work
dry-run output that reports per-host artifact and destination plans
README documentation for native airgap usage and the remaining files: escape hatch

Planned follow-up PRs:

add smoke coverage with local fake or cached bundles, likely after improving smoke-test fixtures
support mode: remoteDownload for mirror-backed environments
support sha256File for release and mirror workflows
add destinationDir and upload-only validation controls for advanced deployments
add cleanup policy for bundles previously placed by k0sctl without deleting arbitrary image files
add per-host airgap overrides once a concrete use case exists
support extra addon/workload bundles while keeping the official k0s bundle as the default path

Copilot

Pull request overview

Adds first-class configuration and execution support for k0s airgap bundles via spec.k0s.airgap, including schema/defaulting/validation, artifact resolution & caching, and a new apply phase to upload bundles to worker-capable Linux hosts.

Changes:

Introduces spec.k0s.airgap API (defaults/validation/path resolution) and documents usage in README.
Adds an airgap package for resolving official/custom bundle artifacts, caching downloads, and checksum verification helpers.
Adds a new AirgapBundles phase and wires it into apply with basic ordering tests.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
README.md	Documents `spec.k0s.airgap` configuration, supported sources/modes, and behavior.
pkg/apis/k0sctl.k0sproject.io/v1beta1/cluster/spec.go	Treats enabled airgap config as “non-empty k0s” and resolves airgap paths relative to baseDir.
pkg/apis/k0sctl.k0sproject.io/v1beta1/cluster/k0s.go	Adds `K0s.Airgap`, defaulting hook, and validation wiring.
pkg/apis/k0sctl.k0sproject.io/v1beta1/cluster/k0s_test.go	Adds tests for airgap defaulting and validation constraints.
pkg/apis/k0sctl.k0sproject.io/v1beta1/cluster/airgap.go	New API type/constants + defaulting/validation/path resolution for airgap config.
pkg/airgap/airgap.go	New artifact resolution, URL template expansion, XDG caching, download, and SHA-256 verification helpers.
pkg/airgap/airgap_test.go	Unit tests for resolver behavior, planning, cache path, checksum verification, and local path resolution.
phase/airgap_bundles.go	New phase to plan/cache/upload bundles to `<data-dir>/images` on worker-capable Linux hosts.
phase/airgap_bundles_test.go	Tests for planning, dry-run output, version requirement, and download de-duplication.
action/apply.go	Inserts `AirgapBundles` into the apply pipeline.
action/apply_test.go	Adds ordering assertions for the new phase relative to worker phases.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.

Copilot

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.

Copilot

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.

Copilot

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 5 comments.

Copilot

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Add native handling for k0s airgap bundles under spec.k0s.airgap so users do not need to model the official bundle upload manually with spec.hosts[*].files. This MVP adds: - schema, defaults, and validation for enabled, source, mode, path, url, and sha256 - support for source: auto, source: local, and source: url in upload mode - official release bundle resolution from spec.k0s.version - local XDG cache storage and per-platform download deduplication - SHA-256 validation for local and custom URL sources - Linux worker-capable host planning for worker, controller+worker, and single roles - upload of bundles to <data-dir>/images before worker install or upgrade work - dry-run output that reports per-host artifact and destination plans - README documentation for native airgap usage and the remaining files: escape hatch Planned follow-up PRs: - add smoke coverage with local fake or cached bundles, likely after improving smoke-test fixtures - support mode: remoteDownload for mirror-backed environments - support sha256File for release and mirror workflows - add destinationDir and upload-only validation controls for advanced deployments - add cleanup policy for bundles previously placed by k0sctl without deleting arbitrary image files - add per-host airgap overrides once a concrete use case exists - support extra addon/workload bundles while keeping the official k0s bundle as the default path Signed-off-by: Kimmo Lehto <klehto@mirantis.com>

Signed-off-by: Kimmo Lehto <klehto@mirantis.com>

Copilot

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.

Signed-off-by: Kimmo Lehto <klehto@mirantis.com>

Copilot

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

kke added the enhancement New feature or request label May 7, 2026

kke requested a review from Copilot May 7, 2026 10:01

Copilot started reviewing on behalf of kke May 7, 2026 10:02 View session

Copilot AI reviewed May 7, 2026

View reviewed changes

Comment thread phase/airgap_bundles.go

Comment thread action/apply.go Outdated

Comment thread action/apply_test.go

kke force-pushed the airgap-mvp branch from 402cb4c to a16b5c2 Compare May 7, 2026 11:17

kke requested a review from Copilot May 7, 2026 11:17

Copilot started reviewing on behalf of kke May 7, 2026 11:18 View session

Copilot AI reviewed May 7, 2026

View reviewed changes

Comment thread pkg/apis/k0sctl.k0sproject.io/v1beta1/cluster/airgap.go Outdated

Comment thread pkg/apis/k0sctl.k0sproject.io/v1beta1/cluster/airgap.go

Comment thread phase/airgap_bundles.go Outdated

kke force-pushed the airgap-mvp branch from a16b5c2 to 082e3aa Compare May 7, 2026 11:29

kke requested a review from Copilot May 7, 2026 11:29

Copilot started reviewing on behalf of kke May 7, 2026 11:30 View session

Copilot AI reviewed May 7, 2026

View reviewed changes

Comment thread pkg/apis/k0sctl.k0sproject.io/v1beta1/cluster/k0s.go

Comment thread pkg/apis/k0sctl.k0sproject.io/v1beta1/cluster/airgap.go

Comment thread pkg/airgap/airgap.go

kke force-pushed the airgap-mvp branch from 082e3aa to 2af64a3 Compare May 7, 2026 12:22

kke requested a review from Copilot May 7, 2026 12:23

Copilot started reviewing on behalf of kke May 7, 2026 12:23 View session

Copilot AI reviewed May 7, 2026

View reviewed changes

Comment thread pkg/airgap/airgap.go

Comment thread pkg/airgap/airgap.go Outdated

Comment thread pkg/airgap/airgap.go

Comment thread pkg/apis/k0sctl.k0sproject.io/v1beta1/cluster/k0s.go Outdated

kke requested a review from Copilot May 8, 2026 11:27

Copilot started reviewing on behalf of kke May 8, 2026 11:27 View session

Copilot AI reviewed May 8, 2026

View reviewed changes

Comment thread action/apply_test.go Outdated

Comment thread pkg/airgap/airgap.go Outdated

kke requested a review from Copilot May 8, 2026 12:04

Copilot started reviewing on behalf of kke May 8, 2026 12:05 View session

Copilot AI reviewed May 8, 2026

View reviewed changes

Comment thread pkg/airgap/airgap.go

Comment thread phase/airgap_bundles.go

Comment thread pkg/apis/k0sctl.k0sproject.io/v1beta1/cluster/k0s.go

kke requested a review from Copilot May 8, 2026 12:56

Copilot started reviewing on behalf of kke May 8, 2026 12:57 View session

Copilot AI reviewed May 8, 2026

View reviewed changes

Comment thread pkg/airgap/airgap.go Outdated

Comment thread pkg/airgap/airgap.go

kke requested a review from Copilot May 8, 2026 13:08

Copilot started reviewing on behalf of kke May 8, 2026 13:09 View session

Copilot AI reviewed May 8, 2026

View reviewed changes

Comment thread phase/airgap_bundles.go

Comment thread pkg/airgap/airgap_test.go Outdated

kke requested a review from Copilot May 8, 2026 13:26

Copilot started reviewing on behalf of kke May 8, 2026 13:26 View session

Copilot AI reviewed May 8, 2026

View reviewed changes

Comment thread phase/airgap_bundles.go

Comment thread phase/airgap_bundles.go Outdated

Comment thread pkg/airgap/airgap.go

kke force-pushed the airgap-mvp branch from e65182d to b3d0b7c Compare May 8, 2026 13:35

kke requested a review from Copilot May 8, 2026 13:36

Copilot started reviewing on behalf of kke May 8, 2026 13:37 View session

kke marked this pull request as ready for review May 8, 2026 13:40

Copilot AI reviewed May 8, 2026

View reviewed changes

Comment thread internal/download/download.go

Comment thread internal/download/download.go Outdated

Comment thread pkg/airgap/airgap.go

Comment thread pkg/airgap/airgap.go Outdated

Comment thread phase/airgap_bundles.go

kke force-pushed the airgap-mvp branch from b3d0b7c to 7d77c8a Compare May 8, 2026 13:51

kke requested a review from Copilot May 8, 2026 13:52

Copilot started reviewing on behalf of kke May 8, 2026 13:52 View session

Copilot AI reviewed May 8, 2026

View reviewed changes

Comment thread internal/download/download.go Outdated

Comment thread action/apply.go

kke added 10 commits May 8, 2026 17:04

fix: tighten airgap checksum handling

e5be617

Signed-off-by: Kimmo Lehto <klehto@mirantis.com>

fix: share bundle download handling

2f49f22

Signed-off-by: Kimmo Lehto <klehto@mirantis.com>

fix: allow defaulted airgap version

7c66218

Signed-off-by: Kimmo Lehto <klehto@mirantis.com>

test: harden airgap phase ordering check

9ad72f4

Signed-off-by: Kimmo Lehto <klehto@mirantis.com>

fix: validate airgap artifact paths

b379398

Signed-off-by: Kimmo Lehto <klehto@mirantis.com>

fix: tighten airgap artifact name validation

5490819

Signed-off-by: Kimmo Lehto <klehto@mirantis.com>

perf: memoize airgap checksum verification

1a78153

Signed-off-by: Kimmo Lehto <klehto@mirantis.com>

fix: validate local airgap bundle directories

3329add

Signed-off-by: Kimmo Lehto <klehto@mirantis.com>

fix: redact airgap download URLs

9c179e3

Signed-off-by: Kimmo Lehto <klehto@mirantis.com>

kke force-pushed the airgap-mvp branch from 7d77c8a to 9c179e3 Compare May 8, 2026 14:04

kke requested a review from Copilot May 8, 2026 14:05

Copilot started reviewing on behalf of kke May 8, 2026 14:05 View session

Copilot AI reviewed May 8, 2026

View reviewed changes

Comment thread internal/download/download.go

fix: redact downloader request errors

e9748d4

Signed-off-by: Kimmo Lehto <klehto@mirantis.com>

kke requested a review from Copilot May 8, 2026 14:14

Copilot started reviewing on behalf of kke May 8, 2026 14:15 View session

Copilot AI reviewed May 8, 2026

View reviewed changes

Conversation

kke commented May 7, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!