# Distro catalog

One YAML file per bootable OS. bootapi selects an entry for a NetBox host
(platform slug / OS family / `provision_template` override) and uses it to build
the iPXE kernel/initrd URLs and pick the kickstart template. Adding an OS is a
YAML + template change here — **no bootapi code change**.

## Fields

| Field | Required | Meaning |
|-------|----------|---------|
| `name` | yes | catalog key; also what a `provision_template` override matches |
| `match.platforms` | one of platforms/family | exact NetBox platform slugs |
| `match.family` | one of platforms/family | NetBox platform family (matches any version) |
| `kickstart` | yes | kickstart template name (`kickstart/<name>.ks.tmpl`) |
| `kernel_url` | yes | Go-template for the installer kernel URL |
| `initrd_url` | yes | Go-template for the installer initrd URL |
| `version_default` | no | version used when the platform slug carries none |
| `kernel_args` | no | extra iPXE kernel args |
| `vars` | no | named Go-template strings exposed to templates as `.DistroVars.<key>` |

`kernel_url`, `initrd_url` and `vars` values are rendered with:
`{{.ArtifactBase}}` (bootapi's `BOOTAPI_ARTIFACT_BASE_URL`), `{{.Version}}`,
`{{.Arch}}`, `{{.Hostname}}`, `{{.Platform}}`, `{{.OSFamily}}`.

## Shipped entries

- **almalinux9** — artifactapi `almalinux` remote, tree
  `almalinux/<ver>/BaseOS/<arch>/os/`.
- **fedora** — artifactapi `fedora` remote, tree
  `fedora/releases/<ver>/Everything/<arch>/os/`.

## Adding another distro (the intended path)

Add `catalog/<name>.yaml` + `kickstart/<name>.ks.tmpl`. If the OS lives on a
mirror bootapi can't already reach, add an artifactapi remote first
(terraform-artifactapi `config/remote_rpm/<name>.yaml`). CI (`bootapi validate`)
will render the new distro against a fixture host and fail the PR if anything is
unresolved.

### Debian / Talos — not implemented, different artifact shapes

These need their own catalog fields/template because their PXE artifacts differ
from the RHEL-family `images/pxeboot/{vmlinuz,initrd.img}` layout:

- **Debian**: netboot installer under
  `dists/<release>/main/installer-<arch>/current/images/netboot/` with
  `linux` + `initrd.gz`, and preseed (not kickstart). A `debian` entry would set
  `kernel_url`/`initrd_url` to those paths and reference a `debian.preseed.tmpl`
  template (and bootapi would serve it from `/ks` unchanged — it's just text).
- **Talos**: immutable OS booted from factory images (`vmlinuz` + `initramfs.xz`
  from the Talos image factory / a mirrored remote), configured by a machine
  config, not a kickstart. A `talos` entry would point `kernel_url`/`initrd_url`
  at the factory artifacts and carry the config URL via `kernel_args`/`vars`.

Both are deferred; this note records the shape so the follow-up is mechanical.