Edit

versions.env Reference

Purpose: For platform engineers, documents every variable in config/versions.env, what it pins, and how the value flows into the build pipeline. Derived from src/opencenter_build/config.py:BuildConfig and the default file written by opencenter-airgap init.

versions.env is the single source of truth for what gets bundled. The build hashes this file (plus components.yaml) into the build state, so any change invalidates the checkpoint.

Format

KEY="value" lines, one per variable. Comments start with #. Quotes are required for values that contain whitespace; the parser uses python-dotenv.

Required variables

The build refuses to start if any of these are missing or empty.

| Variable | Example | Purpose | |---|---|---| | KUBERNETES_VERSION | v1.34.3 | Kubernetes version. Used in kubernetes.version and template-substituted into binary URLs. | | KUBESPRAY_VERSION | master | Kubespray Git ref to clone. | | KUBESPRAY_COMMIT_SHA | HEAD | Optional commit SHA pin. HEAD means follow the ref. | | UBUNTU_VERSION | 24.04 | Target node OS. Used for apt mirroring and image base layer assertions. | | CONTAINER_RUNTIME | containerd | Container runtime. Only containerd is fully supported. | | CONTAINERD_VERSION | 2.1.5 | Containerd version. | | RUNC_VERSION | 1.3.4 | runc version. | | CNI_VERSION | 1.8.0 | CNI plugins version (the standard containernetworking/plugins set, not the higher-level CNI like Calico). | | CNI_PLUGIN | calico | Higher-level CNI. | | CALICO_VERSION | v3.31.3 | Calico version when CNI_PLUGIN=calico. | | TARGET_ARCH | amd64 | Build target architecture. Only amd64 is supported today. | | PYTHON_VERSION | 3.12 | Python version pinned for the bastion virtualenv. |

Service versions

Versions of platform services that ship in the bundle.

| Variable | Example | Purpose | |---|---|---| | FLUXCD_VERSION | v2.7.5 | FluxCD release. | | GITEA_VERSION | v1.25.4 | Gitea release. | | CERT_MANAGER_VERSION | v1.16.2 | cert-manager Helm chart version. Mirrored to charts[] in the manifest. | | INGRESS_NGINX_VERSION | v1.9.0 | ingress-nginx chart version. | | KEYCLOAK_VERSION | 26.0.7 | Keycloak version. | | PROMETHEUS_VERSION | v3.0.1 | Prometheus version. | | GRAFANA_VERSION | 11.4.0 | Grafana version. | | REGISTRY_VERSION | 2.8.3 | The container registry: image used on the bastion. | | NGINX_VERSION | 1.27.3 | The nginx: image used on the bastion file server. |

openCenter GitOps

Where the platform-services GitOps repo lives.

| Variable | Example | Purpose | |---|---|---| | OPENCENTER_GITOPS_BASE_REPO | https://github.com/opencenter-cloud/openCenter-gitops-base | Git URL. | | OPENCENTER_GITOPS_BASE_VERSION | main | Git ref. | | OPENCENTER_GITOPS_BASE_COMMIT_SHA | HEAD | Commit SHA pin. HEAD means follow the ref. | | OPENCENTER_CONTAINER_REGISTRY | ghcr.io/opencenter-cloud | Registry that hosts openCenter-published images. |

Operator tools

CLI tools the bastion bundles for cluster operators. Each becomes an entry in tools[] in the auto-generated manifest.

| Variable | Example | Tool | |---|---|---| | KUBECTL_VERSION | v1.34.3 | kubectl | | HELM_VERSION | v4.0.5 | helm | | K9S_VERSION | v0.50.9 | k9s | | STERN_VERSION | v1.33.1 | stern | | KUBECTX_VERSION | v0.9.5 | kubectx/kubens | | YQ_VERSION | v4.47.2 | yq | | JQ_VERSION | 1.8.1 | jq |

Terraform

Used only when --template openstack was passed to opencenter-airgap init.

| Variable | Example | Purpose | |---|---|---| | TERRAFORM_VERSION | 1.14.0 | Terraform binary version. | | OPENSTACK_PROVIDER_VERSION | 2.1.0 | terraform-provider-openstack. | | LOCAL_PROVIDER_VERSION | 2.5.2 | hashicorp/local. | | NULL_PROVIDER_VERSION | 3.2.3 | hashicorp/null. | | RANDOM_PROVIDER_VERSION | 3.6.3 | hashicorp/random. | | TLS_PROVIDER_VERSION | 4.0.6 | hashicorp/tls. |

How the values flow

  1. opencenter-airgap build parses versions.env into a BuildConfig.

  2. The build calls create_default_manifest(versions_env=…​) (src/opencenter_build/component_manifest.py) to populate kubernetes, tools, repositories, charts, and terraform_providers from the variables above.

  3. Manual edits in the existing config/components.yaml are merged in.

  4. The build hashes both files into build/state.json so checkpoints are invalidated when either changes.

  5. The Zarf manifest generator templates the same values into zarf.yaml (e.g. REGISTRY_VERSION becomes the registry: image used by the local-registry Podman action).

Validation

opencenter-airgap validate runs schema validation against config/schemas/versions.schema.json. It catches:

  • Missing required keys.

  • Empty values.

  • Version strings that do not match ^v?\d+(\.\d+){1,2}.*$ (where the leading v is optional and trailing pre-release/build metadata is allowed).

Run validation before every build:

opencenter-airgap validate

Editing safely

  • Every edit to versions.env regenerates components.yaml on the next build (with manual entries merged on top).

  • Every edit invalidates the build state. Resuming from a checkpoint will fail and ask for --clean.

  • Comments are preserved by python-dotenv.

  • component-manifest-schema.md[Component Manifest Schema] — what the auto-generated components.yaml looks like.

  • cli-commands.md#init[CLI Commands → init] — writes the default versions.env.

  • build-steps.md[Build Steps] — how the build consumes these variables.