Skip to main content

Building Packages

Purpose: For operators, shows how to configure versions.env, add components, and run opencenter-airgap build.

Prerequisites​

  • Ubuntu 24.04 build host with internet access (Zone A)
  • Python 3.10+ and Git 2.30+
  • 100 GB+ free disk space
  • opencenter-airgap CLI installed (pip install -e . from the repo root)
  • Optional: Zarf CLI for final package creation

Steps​

1. Initialize the build environment​

opencenter-airgap init

This creates config/versions.env with default version pins and a config/ directory structure. Use --template openstack if the target environment uses OpenStack (includes Terraform providers):

opencenter-airgap init --template openstack

2. Pin versions in versions.env​

Open config/versions.env and set every version explicitly. This file is the single source of truth for the build:

# config/versions.env (excerpt)
KUBERNETES_VERSION="v1.34.3"
CONTAINERD_VERSION="2.1.5"
RUNC_VERSION="1.3.4"
CALICO_VERSION="v3.31.3"
FLUXCD_VERSION="v2.7.5"
CERT_MANAGER_VERSION="v1.16.2"

Every version referenced in the build comes from this file. Changing a version here and re-running build regenerates components.yaml automatically.

3. Build the package​

opencenter-airgap build

The build command:

  1. Reads config/versions.env and generates config/components.yaml.
  2. Downloads Kubernetes binaries, Helm charts, container images, OS packages, and Python wheels.
  3. Clones and scans repositories (Kubespray, gitops-base) for image references.
  4. Collects everything into assets/ directories.
  5. Generates zarf.yaml from the template.
  6. Produces the final zarf-package-opencenter-airgap-amd64-*.tar.zst in dist/.

Useful flags:

FlagEffect
--cleanRemove previous build artifacts before starting
--resumeResume from last successful checkpoint
--force-regenerateRegenerate components.yaml from scratch (loses manual edits)

4. Add custom components (optional)​

After the initial build, add components that aren't covered by the default manifest:

# Add a custom container image
opencenter-airgap add image custom-registry.io/myapp:v2.1.0

# Add a CLI tool
opencenter-airgap add tool --name mytool --version v1.0 --url https://example.com/mytool-linux-amd64

# Rebuild (preserves manual additions)
opencenter-airgap build

5. Validate before transfer​

opencenter-airgap validate

This checks that all declared components exist in the build output and that zarf.yaml references match the collected assets.

6. Record the checksum​

sha256sum dist/zarf-package-opencenter-airgap-amd64-*.tar.zst > dist/package.sha256

Copy both the .tar.zst and package.sha256 to your transfer media.

Verification​

# Check build status and component counts
opencenter-airgap status

# Verify artifact integrity
opencenter-airgap verify dist/zarf-package-opencenter-airgap-amd64-*.tar.zst

The status command shows each build phase, its state (complete/pending/failed), and the number of collected artifacts.

Troubleshooting​

SymptomLikely causeFix
Build fails downloading imagesRegistry rate limit or network issueRe-run with --resume to continue from checkpoint
components.yaml missing entriesversions.env not updatedEdit versions.env, then opencenter-airgap build
Disk full during buildInsufficient space for images + packagesFree space or mount a larger volume at the build root
zarf.yaml out of syncTemplate not regeneratedRun opencenter-airgap build (regenerates from template)