Skip to main content

Air-Gap Build & Deploy

Purpose: For operators, shows how to resolve air-gap build failures, verification failures, and bastion deployment issues.

Prerequisites​

  • opencenter-airgap CLI installed
  • Docker daemon running (for build operations)
  • Sufficient disk space (builds can exceed 20 GB)

Build Failures​

Image Pull Failure​

Symptom: opencenter-airgap build fails with failed to pull image.

The build host cannot reach the container registry, or the image tag does not exist.

  1. Verify the image exists:
docker pull <image>:<tag>
  1. If the registry requires authentication:
docker login <registry>
  1. Check config/versions.env for typos in image references.

Disk Space Exhaustion​

Symptom: Build fails with no space left on device.

Air-gap packages bundle all container images, charts, and binaries. Check available space:

df -h /var/lib/docker
df -h ./build

Free space by cleaning previous builds:

opencenter-airgap clean
docker system prune -f

Helm Chart Download Failure​

Symptom: failed to fetch chart during build.

Verify the chart exists in the repository at the specified version:

helm repo add <repo-name> <repo-url>
helm search repo <chart-name> --versions

Update config/versions.env or config/components.yaml with a valid version.

Verification Failures​

Digest Mismatch​

Symptom: opencenter-airgap verify reports digest mismatch for image.

The package was modified after build, or the manifest was regenerated without rebuilding.

Rebuild the package:

opencenter-airgap clean
opencenter-airgap build
opencenter-airgap verify

Missing Components​

Symptom: verify reports components present in the manifest but missing from the package.

Components were added to config/components.yaml after the last build. Rebuild to include them.

Bastion Deployment Issues​

Zarf Deploy Fails​

Symptom: zarf package deploy fails on the bastion host.

  1. Verify the package file is intact (transfer corruption):
zstd -t zarf-package-*.tar.zst

  1. Check that the bastion has sufficient disk space and Docker is running.

  2. If ports 5000 or 8080 are in use, stop conflicting services before deploying.

Registry Not Accessible from Nodes​

Symptom: Cluster nodes cannot pull images from the bastion registry.

  1. Verify the bastion registry is running:
curl -s http://<bastion-ip>:5000/v2/_catalog

  1. Check that cluster nodes can reach the bastion on port 5000. Firewall rules or network segmentation may block access.

  2. Verify ContainerD on each node is configured to use the bastion as a mirror. The Kubespray inventory should include the registry mirror configuration.

Package Server Not Serving​

Symptom: opencenter-airgap serve starts but nodes cannot fetch packages.

Check the Nginx container:

docker ps | grep nginx
docker logs <nginx-container-id>

Verify port 8080 is accessible from the cluster network.