Edit

Add a Custom Component

Purpose: For platform engineers, adds an entry to config/components.yaml for a tool, container image, Git repository, or Helm chart that the auto-generated manifest does not include — and survives the next regeneration.

The manifest is auto-generated from config/versions.env. Manual edits are preserved by the merge logic in src/opencenter_build/component_manifest.py:merge_manifests(). The add subcommand is the supported way to make those edits.

Prerequisites

  • A working project (opencenter-airgap init already run).

  • The CLI installed and on $PATH.

Add an image

opencenter-airgap add image my-registry.example.com/payments-api:1.4.2

Adds the reference to images.additional. The build pulls every entry there into the bundled registry. References must include a tag — the build refuses :latest and untagged images.

Add a Helm chart

opencenter-airgap add chart cert-manager \
  --version v1.16.2 \
  --repo https://charts.jetstack.io

Both --version and --repo are required. --repo may be a Helm repository URL or a Git URL.

Add a CLI tool

opencenter-airgap add tool helm \
  --version 4.0.5 \
  --url 'https://get.helm.sh/helm-v{{version}}-linux-amd64.tar.gz' \
  --extract \
  --binary linux-amd64/helm

--version and --url are required. The URL may use {{version}} as a template.

  • --extract extracts the archive and installs the binary at --binary to /usr/local/bin/<name> on the bastion.

  • Without --extract, the tool is treated as a single-file download.

Add a Git repository

opencenter-airgap add repo my-overlay \
  --url https://github.com/example/k8s-overlay.git \
  --ref main

Both --url and --ref are required. --ref may be a branch, tag, or commit SHA. Repositories are cloned into build/<name>/ during the build and scanned for images and Helm releases.

Confirm it landed

grep -A2 "name: payments-api" config/components.yaml || true
yq '.images.additional' config/components.yaml

The generation block at the top of config/components.yaml is metadata only — your additions go below.

Survive a rebuild

The next build merges your additions on top of the generator output:

opencenter-airgap build

If you ever want to discard the manifest entirely and rebuild from versions.env alone, use opencenter-airgap build --force-regenerate. Manual additions are still merged in (see merge_manifests() in src/opencenter_build/component_manifest.py), so this is safe.

Pitfalls

  • Adding an image already present in the auto-discovered list is a no-op. The CLI silently skips duplicates.

  • Adding a chart whose name collides with an auto-generated chart keeps the manual entry. If you want the generator to win, remove your entry first.

  • Editing config/components.yaml by hand still works, but the CLI add is preferred because it validates the inputs.

  • ../reference/component-manifest-schema.md[Component Manifest Schema] — every section and field.

  • ../reference/versions-env.md[versions.env Reference] — the source of truth for auto-generated entries.

  • ../reference/cli-commands.md#add[CLI Commands → add] — flag reference.