Skip to content

Adding a new distro

Distros are a config plug-point. To add one:

  1. Copy the template from config/repos/SCHEMA.md (the section near the bottom). Save it as config/repos/<name>.yaml, e.g. config/repos/ubuntu-noble.yaml.

  2. Fill in the fields:

  3. name — kebab-case identifier; must match the filename stem.
  4. pulp_plugin — deb for apt repos, rpm for yum/dnf repos. RPM support is not yet wired up; use config/repos/rhel9-baseos.yaml.disabled as a stub reference and watch the roadmap.
  5. codename — the upstream codename (e.g. jammy, noble, bookworm). Used to derive pocket labels.
  6. upstream.baseurl — primary URL. Use ${VAR:-default} syntax to allow environment override (matches the validate_upstream.py fallback flow).
  7. upstream.distributions — list each pocket explicitly (e.g. [noble, noble-updates, noble-security]). Each entry expands into its own Pulp remote/repository/distribution.

  8. distribute.base_path — root path under Pulp's content host; arch and pocket are appended automatically.

  9. Validate the file before deploying:

python3 automation/bootstrap/reconcile_pulp.py --validate-config

Errors point you at the offending field; warnings flag unknown keys.

  1. Wire into the environment. Add the distro name to config/environments/low-side.yaml (and high-side.yaml if appropriate):
distros:
  - ubuntu-jammy
  - ubuntu-noble
  - <your-new-distro>

If the distros: list is absent or empty, all enabled *.yaml files in config/repos/ are processed.

  1. Confirm discovery:
python3 automation/bootstrap/reconcile_pulp.py --list-distros
  1. Dry-run the reconcile, then apply, then sync and publish:
python3 automation/bootstrap/reconcile_pulp.py                   # dry-run
python3 automation/bootstrap/reconcile_pulp.py --apply           # create remotes/repos
python3 automation/bootstrap/reconcile_pulp.py --apply --sync --publish
  1. Validate upstream reachability (optional but recommended for first-run):
python3 automation/bootstrap/validate_upstream.py --allow-fallback

Adding a stub-only distro (no runtime support yet)

If you want to commit a config but skip it at reconcile time — for example, because the Pulp image is missing the required plugin — name the file <name>.yaml.disabled. The reconcile glob is strictly *.yaml, so disabled stubs are ignored automatically. See:

  • config/repos/debian-bookworm.yaml.disabled
  • config/repos/rhel9-baseos.yaml.disabled

When the runtime catches up, rename to <name>.yaml and add to the env's distros: list.