Build Steps Reference

Purpose: For operators, provides each build phase with inputs, outputs, duration, and failure modes.

Overview

opencenter-airgap build executes phases sequentially. Each phase checkpoints on completion, enabling --resume after failures.

Build Phases

Phase 1: Generate Manifest

Field	Value
Input	config/versions.env
Output	config/components.yaml
Duration	< 5 seconds
Skipped when	components.yaml exists and versions.env unchanged (unless --force-regenerate)

Reads versions.env and produces components.yaml with resolved URLs, versions, and checksum references. Manual additions in components.yaml are preserved unless --force-regenerate is passed.

Failure mode: invalid variable in versions.env → exits with parse error and line number.

Phase 2: Clone Repositories

Field	Value
Input	repositories section of components.yaml
Output	build/kubespray/, build/openCenter-gitops-base/
Duration	1–5 minutes (depends on network and repo size)
Skipped when	Repos already cloned at the pinned commit SHA

Clones Git repositories at the commit SHA specified in versions.env. If KUBESPRAY_COMMIT_SHA=HEAD, clones the branch tip (not recommended for reproducibility).

Failure mode: network timeout or invalid SHA → retry with --resume.

Phase 3: Scan for Images

Field	Value
Input	Cloned repositories in build/
Output	Updated images section in components.yaml
Duration	10–30 seconds
Skipped when	No repositories configured for auto-discovery

Parses YAML files in Kubespray roles (roles/*/defaults/main.yml) and gitops-base manifests for image: references. Merges discovered images into components.yaml, deduplicating by reference.

Failure mode: malformed YAML in scanned file → logs warning, continues scanning.

Phase 4: Download Kubernetes Binaries

Field	Value
Input	kubernetes.binaries in components.yaml
Output	assets/k8s-binaries/ (kubectl, kubelet, kubeadm)
Duration	1–3 minutes
Skipped when	Binaries exist with matching checksums

Downloads each binary and verifies against the upstream .sha256 checksum file.

Failure mode: checksum mismatch → deletes partial download, retries on --resume.

Phase 5: Download Tools

Field	Value
Input	tools section of components.yaml
Output	assets/tools/ (helm, k9s, stern, yq, jq)
Duration	1–2 minutes
Skipped when	Tools exist at expected versions

Downloads and extracts (where extract: true) CLI tools.

Failure mode: 404 or connection error → logs the failed URL, continues with remaining tools.

Phase 6: Download Container Images

Field	Value
Input	images section of components.yaml
Output	assets/images/ (OCI tarballs)
Duration	10–60 minutes (depends on image count and network)
Skipped when	Image tarballs exist with matching tags

Pulls each image and saves as an OCI tarball. This is typically the longest phase.

Failure mode: registry rate limit (HTTP 429) → backs off and retries. Use --resume if the build is interrupted.

Phase 7: Download Helm Charts

Field	Value
Input	charts section of components.yaml
Output	assets/charts/
Duration	1–2 minutes
Skipped when	Charts exist at expected versions

Pulls chart archives from Helm repositories.

Failure mode: chart version not found → exits with error naming the chart and repo URL.

Phase 8: Collect OS Packages and Python Wheels

Field	Value
Input	Kubespray requirements, versions.env
Output	assets/repos/, assets/python-wheels/
Duration	5–15 minutes
Skipped when	Package directories populated

Downloads Ubuntu packages and Python wheels needed by Kubespray and Ansible.

Failure mode: missing package in upstream repo → logs error with package name.

Phase 9: Mirror Terraform Providers

Field	Value
Input	Provider versions in versions.env
Output	assets/terraform-mirror/
Duration	1–3 minutes
Skipped when	DEPLOYMENT_MODE=baremetal (no Terraform needed)

Creates a filesystem mirror for Terraform providers (OpenStack, local, null, random, TLS).

Failure mode: provider version not found in registry → exits with error.

Phase 10: Generate Zarf Package

Field	Value
Input	zarf.yaml.template, all assets/ directories
Output	dist/zarf-package-opencenter-airgap-amd64-*.tar.zst
Duration	5–15 minutes (compression time)
Skipped when	Never (always runs as final step)

Generates zarf.yaml from the template, then runs zarf package create to produce the compressed, signed artifact with SBOM.

Failure mode: Zarf CLI not installed → exits with instructions to install Zarf.

Checkpoint File

Build state is stored in build/.state.json. Each phase records:

{
  "phase": "download_images",
  "status": "complete",
  "started_at": "2026-02-05T08:20:00Z",
  "completed_at": "2026-02-05T08:45:12Z",
  "artifact_count": 47,
  "versions_env_hash": "sha256:abc123..."
}

Delete build/.state.json to force a full rebuild.