Component Manifest Schema

Purpose: For operators, provides JSON schema for components.yaml with field definitions and validation rules.

Overview

config/components.yaml declares every artifact included in the air-gap package. It is auto-generated from config/versions.env by opencenter-airgap build. Manual additions (custom images, tools) are preserved across regenerations unless --force-regenerate is used.

Top-Level Structure

_generated:          # Metadata block (auto-managed)
kubernetes:          # Kubernetes binaries
tools:               # CLI tools and utilities
repositories:        # Git repositories to clone and scan
images:              # Container images
charts:              # Helm charts

_generated (metadata)

Field	Type	Description
timestamp	string (ISO 8601)	When the manifest was last generated
source	string	Path to the source file (config/versions.env)
tool	string	Tool that generated the manifest (opencenter-airgap)
note	string	Human-readable note about auto-generation

This block is overwritten on every generation. Do not edit it manually.

kubernetes

Field	Type	Required	Description
version	string	yes	Kubernetes version (without v prefix)
binaries	list	yes	List of binary definitions

Each binary entry:

Field	Type	Required	Description
name	string	yes	Binary name (kubectl, kubelet, kubeadm)
url	string	yes	Download URL (supports {{version}} template)
checksum_url	string	no	URL to .sha256 checksum file

Example:

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

tools

List of CLI tools to download.

Field	Type	Required	Description
name	string	yes	Tool name
version	string	yes	Version (without v prefix)
url	string	yes	Download URL (supports {{version}} template)
checksum_url	string	no	Checksum URL (null if unavailable)
extract	boolean	yes	Whether the download is an archive to extract
binary	string	no	Path to binary within archive (when extract: true)

Example:

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

repositories

Git repositories to clone for scanning and inclusion.

Field	Type	Required	Description
name	string	yes	Repository identifier
url	string	yes	Git clone URL
ref	string	yes	Branch name or tag
type	string	yes	Always git

Example:

repositories:
  - name: kubespray
    url: https://github.com/kubernetes-sigs/kubespray.git
    ref: master
    type: git

Pin to a specific commit using KUBESPRAY_COMMIT_SHA in versions.env for reproducibility.

images

Container images to include.

Field	Type	Required	Description
auto_discover	list	no	Rules for scanning repos
(inline entries)	string	no	Explicit image references added via add image

Auto-discover entry:

Field	Type	Description
source	string	Reference to a repository (e.g., repositories.kubespray)
patterns	list of strings	Glob patterns for files to scan

Example:

images:
  auto_discover:
    - source: repositories.kubespray
      patterns:
        - roles/*/defaults/main.yml
        - inventory/*/group_vars/*.yml

charts

Helm charts to download.

Field	Type	Required	Description
name	string	yes	Chart name
repo	string	yes	Helm repository URL
version	string	yes	Chart version
path	string	no	Subdirectory within a Git repo (for Git-hosted charts)
ref	string	no	Git ref (for Git-hosted charts)

Example:

charts:
  - name: cert-manager
    repo: https://charts.jetstack.io
    version: v1.16.2

Validation Rules

• Every url field must be a valid HTTP/HTTPS URL or use the {{version}} template syntax.
• Image references must include an explicit tag (e.g., nginx:1.27.3, not nginx or nginx:latest).
• The name field must be unique within its section.
• Run opencenter-airgap validate to check the manifest against these rules.