Build Steps Reference

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

Overview

opencenter-airgap build executes 8 phases sequentially. Each phase checkpoints on completion to build/state.json, enabling --resume after failures.

Total build time: 30–90 minutes depending on network speed and image count.

Output: dist/zarf-package-opencenter-airgap-amd64-*.tar.zst (~25 GB compressed)

Build Phases

Phase 1: scan_repositories

Field	Value
Input	config/versions.env (repository URLs and refs)
Output	build/ (cloned repos), config/all-images.txt
Duration	1–5 minutes
Skipped when	Repos already cloned at pinned commit SHA

Clones Git repositories (Kubespray, openCenter-gitops-base) at commit SHAs from versions.env. Scans YAML files for image: references.

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

Phase 2: collect_helm_charts

Field	Value
Input	Cloned repositories in build/
Output	config/helm-charts.txt, config/helm-repos.txt
Duration	10–30 seconds
Skipped when	Chart lists already generated

Walks cloned repos for HelmRelease and HelmRepository resources. Extracts chart names, versions, and repository URLs.

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

Phase 3: generate_kubespray_lists

Field	Value
Input	Kubespray repo in build/kubespray/
Output	config/kubespray-files.txt, config/kubespray-images.txt
Duration	30–60 seconds
Skipped when	Lists already generated

Runs Kubespray's generate_list.sh to produce definitive lists of required files and container images for the target Kubernetes version.

Failure mode: Kubespray script error → exits with stderr output.

Phase 4: mirror_terraform_providers

Field	Value
Input	Provider versions in versions.env
Output	assets/terraform-mirror/
Duration	1–3 minutes
Skipped when	Mirror already populated at correct versions

Creates a filesystem mirror for Terraform providers (OpenStack, local, null, random, TLS). Only for OpenStack template — baremetal deployments skip this.

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

Phase 5: organize_assets

Field	Value
Input	All generated lists, components.yaml
Output	assets/ (k8s-binaries, tools, images, charts, repos, python-wheels)
Duration	10–60 minutes (longest phase)
Skipped when	Assets exist with matching checksums

Downloads all artifacts:

• Kubernetes binaries (kubectl, kubelet, kubeadm, runc, containerd)
• CLI tools (helm, k9s, stern, yq, jq, kubectx)
• Container images (139+ OCI tarballs)
• Helm charts
• Ubuntu apt packages
• Python wheels (Ansible, Kubespray dependencies)

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

Phase 6: generate_zarf_yaml

Field	Value
Input	zarf.yaml.template, versions.env variables
Output	zarf.yaml
Duration	< 5 seconds
Skipped when	Never

Renders zarf.yaml.template with all version variables and component definitions. The generated file defines 4 Zarf components: bootstrap-tools, kubespray-core, k8s-images, deploy-cluster.

Failure mode: template syntax error → exits with render error and line number.

Phase 7: create_zarf_package

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

Runs zarf package create to produce the compressed .tar.zst artifact with embedded SBOM and SHA-256 checksum. If Cosign keys exist in .secrets/, signs the package.

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

Phase 8: generate_manifest

Field	Value
Input	dist/ contents
Output	dist/artifact-manifest.json
Duration	< 10 seconds
Skipped when	Never

Writes artifact-manifest.json containing SHA-256 checksums of all produced artifacts. Used for verification at Zone B/C boundary.

Failure mode: unlikely (local file operations only).

Checkpoint State

Build state is stored in build/state.json:

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

Resuming Builds

# Resume from last checkpoint
opencenter-airgap build --resume

# Force full rebuild
opencenter-airgap build --clean

# Regenerate components.yaml then build
opencenter-airgap build --force-regenerate

Zarf Variables (in generated zarf.yaml)

Variable	Default	Description
SSH_USER	deployer	SSH user for bastion operations
INSTALL_PATH	/opt/opencenter	Base installation directory
REGISTRY_PORT	35000	Container registry listen port
NGINX_PORT	80	File server listen port