Adding Custom Images
Purpose: For operators, shows how to include additional container images beyond defaults.
Prerequisites
opencenter-airgapCLI installed and initialized- A completed or in-progress build environment
- Image references for the custom workloads you need in Zone C
When You Need Custom Images
The default build collects images for Kubernetes system components, Calico CNI, FluxCD, and platform services defined in openCenter-gitops-base. If your deployment includes application workloads, third-party operators, or custom services, those images must be added explicitly.
Steps
1. Identify required images
List every image your workloads reference. Check Helm values, Deployment manifests, and DaemonSet specs:
# Extract images from a Helm chart's values
helm template my-release my-chart/ | grep "image:" | sort -u
# Extract images from existing manifests
grep -rh "image:" manifests/ | sed 's/.*image: *//' | sort -u
2. Add images to the manifest
opencenter-airgap add image ghcr.io/org/webapp:v2.4.0
opencenter-airgap add image docker.io/library/redis:7.2-alpine
opencenter-airgap add image quay.io/prometheus/node-exporter:v1.7.0
Each call appends to the images section of config/components.yaml. The image reference must include a tag — untagged references are rejected.
3. Bulk-add from a file
For larger lists, create a text file with one image per line:
# custom-images.txt
ghcr.io/org/webapp:v2.4.0
ghcr.io/org/worker:v2.4.0
docker.io/library/redis:7.2-alpine
docker.io/library/postgres:16.1-alpine
while read -r img; do
opencenter-airgap add image "$img"
done < custom-images.txt
4. Discover images from scanned repositories
If your application code lives in a Git repository with Kubernetes manifests, the scanner can extract image references automatically:
opencenter-airgap scan --repo /path/to/app-repo
The scanner parses YAML files for image: fields and adds discovered references to components.yaml.
5. Rebuild the package
opencenter-airgap build --resume
The --resume flag skips already-downloaded artifacts and only fetches the newly added images.
6. Verify images are included
opencenter-airgap status
Check the image count matches your expectations. For a specific image:
grep "ghcr.io/org/webapp" config/components.yaml
How Images Are Served in Zone C
After zarf package deploy on the bastion, images are loaded into the local registry on port 35000. Kubespray configures containerd on target nodes to use <BASTION_IP>:35000 as a mirror. Pods referencing ghcr.io/org/webapp:v2.4.0 transparently pull from the bastion registry.
No image reference rewriting is needed in your manifests — the containerd mirror configuration handles the redirect.
Verification
On a target node in Zone C, confirm the image is available:
crictl pull <BASTION_IP>:35000/org/webapp:v2.4.0
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
add image rejects the reference | Missing tag (e.g., myapp instead of myapp:v1) | Always include an explicit tag |
| Image not in registry after deploy | Image was added after last build | Re-run opencenter-airgap build --resume and redeploy |
Pull fails with manifest unknown | Image name path differs between source and mirror | Check the exact repository path in components.yaml |
| Rate-limited during download | Docker Hub anonymous pull limit | Authenticate with docker login before building, or use --resume to retry |