Migrating to Simplified Workflow

Purpose: For operators, shows how to convert from legacy bash build to Python CLI with rollback path.

Prerequisites

• Existing air-gap build environment using the legacy bash scripts
• Python 3.10+ installed on the build host
• Access to the openCenter-AirGap repository (latest version)

What Changed

The legacy workflow used standalone bash scripts to download dependencies, assemble directories, and manually create Zarf packages. The new opencenter-airgap Python CLI replaces that with:

• A single versions.env file as the source of truth for all version pins.
• Auto-generated components.yaml manifest (replaces hand-maintained file lists).
• Checkpoint/resume support — failed builds continue from the last successful step.
• Built-in scan, validate, and verify commands.
• Structured logging and build metrics.

Steps

1. Install the new CLI

cd openCenter-AirGap
pip install -e .
opencenter-airgap version

2. Back up your existing build

cp -r config/ config.legacy-backup/
cp -r dist/ dist.legacy-backup/

3. Initialize the new environment

opencenter-airgap init

This creates a fresh config/versions.env. Do not overwrite it yet.

4. Port your version pins

Open your legacy configuration (typically scattered across multiple scripts or env files) and transfer each version into config/versions.env:

# Compare legacy versions with new defaults
diff config.legacy-backup/versions.env config/versions.env

Copy version values from the legacy config into the new versions.env. The variable names are documented in the file comments.

5. Port custom components

If your legacy build included custom images or tools not covered by the defaults, add them:

opencenter-airgap add image registry.example.com/custom-app:v1.0
opencenter-airgap add tool --name custom-tool --version v2.0 --url https://example.com/tool.tar.gz

6. Run the new build

opencenter-airgap build

The CLI generates components.yaml from versions.env, downloads all artifacts, and produces the Zarf package.

7. Compare outputs

Verify the new package contains the same components as the legacy build:

opencenter-airgap status

# Compare image lists
diff <(sort config.legacy-backup/all-images.txt) <(grep 'image:' config/components.yaml | awk '{print $NF}' | sort)

8. Test in a non-production Zone C

Deploy the new package to a test bastion before using it in production:

zarf package deploy zarf-package-opencenter-airgap-amd64-*.tar.zst --confirm

Verify registry and nginx are serving correctly, then run a test cluster deployment.

Rollback Path

If the new CLI produces an unusable package, restore the legacy build:

cp -r config.legacy-backup/* config/
cp -r dist.legacy-backup/* dist/

Then use the legacy bash scripts as before. The new CLI does not modify legacy scripts — both workflows can coexist in the same repository.

Verification

# Validate the new manifest
opencenter-airgap validate

# Verify the built package
opencenter-airgap verify dist/zarf-package-opencenter-airgap-amd64-*.tar.zst

Troubleshooting

Symptom	Likely cause	Fix
Missing images in new build	Custom images not ported from legacy	Add them with opencenter-airgap add image
versions.env variable not recognized	Variable name changed between versions	Check the default versions.env comments for current names
Build fails at scan step	Repository URLs changed	Update OPENCENTER_GITOPS_BASE_REPO in versions.env
Package size differs significantly	Different image versions or missing components	Run opencenter-airgap status and compare component counts