Component Manifest Schema :: openCenter Community Documentation

Component Manifest Schema

Purpose: For platform engineers, documents every section and field of config/components.yaml. Derived from the dataclasses in src/opencenter_build/component_manifest.py (ComponentManifest and friends). The build refuses unknown fields.

components.yaml is auto-generated from versions.env on the first build (see ../operations/migrate-to-versions-env.md[Migrate to versions.env]). You can also edit it by hand or via opencenter-airgap add. Manual additions are merged on regeneration.

Top-level structure

_generated:
  timestamp: 2026-02-05T08:18:05.211440+00:00
  source: config/versions.env
  tool: opencenter-airgap
  note: This file is auto-generated. Manual edits are preserved during regeneration.

kubernetes: {...}
tools: [...]
repositories: [...]
images:
  auto_discover: [...]
  additional: [...]
charts: [...]
os_packages: {...}
python_packages: {...}
terraform_providers: [...]

Every top-level key is optional. The build skips empty sections.

The _generated block is informational. The build neither reads nor enforces it.

`kubernetes`

Pinned Kubernetes binaries. Single object.

kubernetes:
  version: 1.34.3
  binaries:
    - name: kubectl
      url: https://dl.k8s.io/v{{version}}/bin/linux/amd64/kubectl
      checksum_url: https://dl.k8s.io/v{{version}}/bin/linux/amd64/kubectl.sha256
    - name: kubelet
      url: https://dl.k8s.io/v{{version}}/bin/linux/amd64/kubelet
      checksum_url: https://dl.k8s.io/v{{version}}/bin/linux/amd64/kubelet.sha256
    - name: kubeadm
      url: https://dl.k8s.io/v{{version}}/bin/linux/amd64/kubeadm
      checksum_url: https://dl.k8s.io/v{{version}}/bin/linux/amd64/kubeadm.sha256

| Field | Type | Required | Notes | |---|---|---|---| | version | string | yes | Kubernetes version. {{version}} in URLs is substituted from this field. | | binaries[] | list | yes | Each binary has name, url, and optional checksum_url. | | binaries[].name | string | yes | Binary name on disk. | | binaries[].url | string | yes | Download URL. May contain {{version}}. | | binaries[].checksum_url | string | no | URL of a .sha256 file used during download. |

`tools`

CLI tools to bundle. List of objects.

tools:
  - name: helm
    version: 4.0.5
    url: https://get.helm.sh/helm-v{{version}}-linux-amd64.tar.gz
    checksum_url: null
    extract: true
    binary: linux-amd64/helm
  - name: yq
    version: 4.47.2
    url: https://github.com/mikefarah/yq/releases/download/v{{version}}/yq_linux_amd64
    extract: false

| Field | Type | Required | Notes | |---|---|---|---| | name | string | yes | Tool name. Used as binary filename when extract: false. | | version | string | yes | Tool version (no leading v). | | url | string | yes | Download URL. May contain {{version}}. | | checksum_url | string | no | URL of a checksum file. | | extract | bool | no, default false | Extract the downloaded archive. | | binary | string | required if extract: true | Path to the binary inside the archive. |

`repositories`

Git repositories to clone for image and chart discovery. List of objects.

repositories:
  - name: kubespray
    url: https://github.com/kubernetes-sigs/kubespray.git
    ref: master
    type: git
  - name: openCenter-gitops-base
    url: https://github.com/opencenter-cloud/openCenter-gitops-base
    ref: main
    type: git

| Field | Type | Required | Notes | |---|---|---|---| | name | string | yes | Directory name under build/. Must be unique. | | url | string | yes | Git clone URL (HTTPS or SSH). | | ref | string | yes | Branch, tag, or commit SHA. | | type | string | no, default git | Currently only git is supported. |

opencenter-airgap scan --repos clones each entry into build/<name>/. The build pipeline scans the cloned repos for images and Helm charts.

`images`

Container images. Two ways to populate:

images:
  auto_discover:
    - source: repositories.kubespray
      patterns:
        - roles/*/defaults/main.yml
        - inventory/*/group_vars/*.yml
  additional:
    - my-registry.example.com/payments-api:1.4.2

`images.auto_discover`

| Field | Type | Required | Notes | |---|---|---|---| | source | string | yes | Reference to a repository in repositories[] using repositories.<name>. | | patterns[] | list of strings | yes | Glob patterns relative to the repo root. Files matching any pattern are scanned for image references. |

The scanner is src/opencenter_build/scanner.py:RepositoryScanner. It looks for image-shaped tokens in the matched files and deduplicates them.

`images.additional`

A flat list of fully-qualified image references. Pin every entry to a tag — the build rejects :latest and untagged references.

`charts`

Helm charts to mirror. List of objects.

charts:
  - name: cert-manager
    repo: https://charts.jetstack.io
    version: v1.16.2
  - name: my-app
    repo: https://github.com/example/charts.git
    version: ""        # ignored when ref is set
    path: charts/my-app
    ref: main

| Field | Type | Required | Notes | |---|---|---|---| | name | string | yes | Chart name. | | repo | string | yes | Helm repo URL or Git URL. | | version | string | yes | Chart version. May be empty for Git-based charts pinned by ref. | | path | string | no | Path to the chart inside a Git repo. | | ref | string | no | Git ref for Git-based charts. |

`os_packages` and `python_packages`

OS apt packages and Python wheels. Both share the same shape.

os_packages:
  source: kubespray-offline
  additional:
    - htop
    - tcpdump

python_packages:
  source: kubespray-offline
  additional:
    - kubernetes==32.0.0
    - hvac==2.3.0

| Field | Type | Required | Notes | |---|---|---|---| | source | string | no, default kubespray-offline | Where the bulk packages come from. Currently only kubespray-offline is supported. | | additional[] | list of strings | no | Extra packages to bundle on top of the source set. |

Empty additional lists are dropped from serialized output.

`terraform_providers`

Terraform providers to mirror for offline OpenStack deploys. List of objects.

terraform_providers:
  - name: openstack
    source: terraform-provider-openstack/openstack
    version: 2.1.0
  - name: local
    source: hashicorp/local
    version: 2.5.2

| Field | Type | Required | Notes | |---|---|---|---| | name | string | yes | Provider name. | | source | string | yes | Provider source address (namespace/name). | | version | string | yes | Pinned version. |

The build mirrors providers using scripts/build/mirror_terraform_providers.sh and writes a .terraformrc referencing the mirror at deploy time.

Validation

Validation runs in two places:

opencenter-airgap validate runs the ComprehensiveConfigValidator from src/opencenter_build/validation.py. It checks required fields, unique names, and version format.
opencenter-airgap build runs the same validator before any work, and refuses to start on errors.

JSON schemas for adjacent files (versions.env, Zarf variables, node inventory) live under config/schemas/. There is no JSON schema for components.yaml today — the dataclass definitions are the schema.

Common errors

Component name 'My-Tool' is invalid — tool, repo, and chart names must be lowercase, start with a letter, and use only [a-z0-9-].
Image '<name>:latest' uses mutable tag — pin to a specific version.
Duplicate component name — two entries in the same section share a name.
URL must be HTTPS — http:// is rejected outside localhost.

versions-env.md[versions.env Reference] — variables that flow into the auto-generated manifest.
cli-commands.md#add[CLI Commands → add] — the supported way to add components.
build-steps.md[Build Steps] — how the manifest is consumed during a build.