Air-Gap Code Structure
Purpose: For contributors, provides Air-Gap Python package layout and build pipeline modules.
Package layout
openCenter-AirGap/
├── src/opencenter_build/ # Main package
│ ├── __init__.py # Package init, version
│ ├── cli.py # Typer CLI (all commands)
│ ├── orchestrator.py # Build pipeline orchestration (8 steps)
│ ├── component_manifest.py # Manifest dataclasses, merge_manifests()
│ ├── scanner.py # Repository image/chart scanner
│ ├── manifest.py # Artifact manifest generation
│ ├── config.py # BuildConfig from versions.env
│ ├── validation.py # ComprehensiveConfigValidator, schema checks
│ ├── verifier.py # PackageVerifier (checksum + signature)
│ ├── state.py # Atomic state management (checkpointing)
│ ├── image_utils.py # Image reference parsing/validation
│ ├── version_utils.py # Version string validation
│ ├── zarf_generator.py # Zarf YAML generation from template
│ ├── zarf_utils.py # Zarf CLI interaction utilities
│ ├── downloader.py # Asset download with retries
│ ├── provenance.py # Build provenance tracking
│ ├── provenance_kubespray.py # Kubespray-specific provenance
│ ├── secrets.py # SecretsManager (.secrets/ directory)
│ ├── transaction.py # Rollback support
│ ├── metrics.py # Build metrics collection
│ ├── logging.py # Centralized logging setup
│ └── exceptions.py # Exception hierarchy
├── config/ # Configuration files
│ ├── versions.env # Version pins (source of truth)
│ ├── components.yaml # Component manifest
│ └── schemas/ # JSON Schema validation files
│ ├── versions.schema.json
│ ├── zarf-variables.schema.json
│ ├── openstack-config.schema.json
│ └── nodes.schema.json
├── scripts/ # Shell scripts
│ ├── release.sh # CI release tagging
│ ├── cleanup.sh # Environment cleanup
│ ├── lib/ # Shared bash libraries
│ │ ├── download.sh
│ │ ├── logging.sh
│ │ └── secrets.sh
│ ├── hooks/
│ │ └── check-generated-files.sh
│ └── deploy/ # 24 deployment scripts
│ ├── deploy.sh # Main orchestration
│ ├── deploy_kubespray.sh
│ ├── install_fluxcd.sh
│ ├── terraform_openstack.sh
│ ├── validate_bastion_setup.sh
│ └── ...
├── tests/ # Test suite
│ ├── unit/ # Unit tests
│ ├── property/ # Hypothesis property-based tests
│ └── integration/ # Integration tests
├── testdata/ # Test fixtures
├── zarf.yaml.template # Zarf package template
├── pyproject.toml # Project metadata and tool config
└── mise.toml # Mise tool versions
Module responsibilities
| Module | Responsibility |
|---|---|
cli.py | Typer-based CLI. Defines all commands (init, add, scan, generate-manifest, build, validate, verify, status, clean, serve, keygen, release, version). Entry point registered as opencenter-airgap. |
orchestrator.py | Coordinates the 8-step build pipeline with checkpointing. Steps: scan_repositories → collect_helm_charts → generate_kubespray_lists → mirror_terraform_providers → organize_assets → generate_zarf_yaml → create_zarf_package → generate_manifest. |
config.py | Loads versions.env via python-dotenv. Exposes BuildConfig dataclass with all version pins. |
component_manifest.py | Dataclasses for components (images, charts, tools, repos, OS packages, Python packages). merge_manifests() preserves manual add edits across regeneration. |
scanner.py | Clones repos, walks YAML for image: fields and HelmRelease/HelmRepository resources. Outputs to config/all-images.txt, config/helm-charts.txt. |
manifest.py | Generates dist/artifact-manifest.json with checksums for all produced artifacts. |
state.py | Atomic state persistence to build/state.json. Supports resume after failure. |
transaction.py | Wraps build steps in transactions with rollback on failure. |
validation.py | ComprehensiveConfigValidator — schema validation via jsonschema, cross-reference checks, URL reachability. |
verifier.py | PackageVerifier — SHA-256 checksum + Cosign signature verification. |
image_utils.py | Image reference parsing, validation, and normalization. |
version_utils.py | Semver parsing and validation. |
zarf_generator.py | Renders zarf.yaml.template with variables from config. |
zarf_utils.py | Wraps zarf CLI for package create and package deploy. |
downloader.py | Downloads assets with retry logic and progress reporting. |
provenance.py | Tracks build provenance (what was downloaded, when, from where). |
secrets.py | SecretsManager for .secrets/ directory (Cosign keys, registry creds). Mode 0700. |
metrics.py | Collects build timing, counts, and package sizes. |
logging.py | Configures Rich-based structured logging. |
exceptions.py | Hierarchy: BuildError, ConfigError, ValidationError, ScanError, DownloadError. |
Entry point
Registered in pyproject.toml:
[project.scripts]
opencenter-airgap = "opencenter_build.cli:main"
Key dependencies (pinned)
| Package | Version | Purpose |
|---|---|---|
| jsonschema | 4.26.0 | Configuration validation |
| pyyaml | 6.0.3 | YAML parsing |
| typer | 0.25.1 | CLI framework |
| rich | 15.0.0 | Terminal output formatting |
| python-dotenv | 1.2.2 | Loading versions.env files |
Dev dependencies
| Package | Version | Purpose |
|---|---|---|
| pytest | 9.0.3 | Test framework |
| pytest-timeout | 2.4.0 | Test timeouts (300s) |
| pytest-cov | 7.1.0 | Coverage reporting |
| hypothesis | 6.152.6 | Property-based testing |
| black | 26.3.1 | Code formatting (100 char) |
| mypy | 2.1.0 | Static type checking |
| pylint | 4.0.5 | Linting |
| pre-commit | 4.6.0 | Git hooks |
Build Pipeline Detail
The orchestrator runs 8 steps sequentially with checkpoints:
scan_repositories
└→ collect_helm_charts
└→ generate_kubespray_lists
└→ mirror_terraform_providers
└→ organize_assets
└→ generate_zarf_yaml
└→ create_zarf_package
└→ generate_manifest
Each step writes completion state to build/state.json. Use --resume to restart from last successful step. Use --clean to discard all state and start fresh.
Output: dist/zarf-package-opencenter-airgap-amd64-*.tar.zst (~25 GB compressed) + SBOM + checksum + Cosign signature + artifact-manifest.json.