0036. ichor images list cannot resolve catalogs or schematics, and says so

Status: Superseded by ADR 0090 (the command was removed) · Date: 2026-10-26 · Design section: Monitoring and registry mirrors

Decided: ichor images list prints the five fixed Image Factory images (version-gated) plus an unconditional warning naming the two catalogs, instead of trying to resolve a schematic's extensions/overlays into images

Context

architecture.md's "Monitoring and registry mirrors" section names what ichor images list has to print -- siderolabs/imager, siderolabs/installer-base (siderolabs/installer below Talos 1.10.0), siderolabs/extensions, siderolabs/overlays, siderolabs/talosctl-all (1.11.0 and up) -- and names the trap explicitly: "extensions and overlays are catalogs ... every extension and overlay image they reference has to be mirrored too ... A mirror that holds the five images above and nothing else looks complete and fails at the first schematic that asks for an extension."

This unit's own acceptance criteria required answering, not assuming, whether Ichor can resolve a catalog's or a schematic's contents into concrete image references -- and forbade solving it by connecting to anything: "実際にレジストリへ接続しないこと ... 接続が必要な設計になるな ら、それは差し戻し案件です" (never connect to a registry; a design that needs to is grounds for rejection).

Research

Checked against the siderolabs/image-factory repository directly (docs/api.md, docs/sources.md, docs/air-gapped.md, hack/copy-artifacts.sh, 2026-10-26):

• The schematic itself is opaque to Ichor. TalosClusterSchematic (api/v1alpha1/taloscluster_types.go) stores only Image Factory's schematic ID -- a content hash, not the customization that produced it. Recovering what extensions/overlays a schematic names requires GET /schematics/:id, a call to Image Factory's own HTTP API.
• There is no endpoint that resolves a schematic ID straight to image references. GET /schematics/:id returns the schematic's YAML body (extension/overlay names); GET /version/:version/extensions/official and .../overlays/official list what each Talos version makes available, also by name. Nothing in the documented API turns a name into the image reference Ichor would need to print.
• The catalogs (siderolabs/extensions, siderolabs/overlays) are themselves OCI images, not an HTTP-fetchable manifest. hack/copy-artifacts.sh resolves them by pulling the catalog image and reading a YAML manifest out of its filesystem; there is no documented way to get that mapping without pulling the image.

So resolving "what does this schematic actually need mirrored" needs at least one network call no matter which path is taken -- Image Factory's API, or pulling a catalog image -- and this command's acceptance criteria rule out both.

Decision

buildImageList (internal/cli/images_list.go) only ever returns the five version-keyed names architecture.md already settled, computed entirely offline from a Talos version string (golang.org/x/mod/semver, already a direct dependency via pkg/upgrade, handles the two version boundaries -- 1.10.0 for installer/installer-base, 1.11.0 for talosctl-all -- so this adds no new version-comparison code). --schematic is accepted as a flag (matching the design's "a given version set" of Talos version plus schematic) but is never read by buildImageList: it exists so a future resolving implementation has a place to land, not as a currently-functional input. Its doc comment (imagesListOptions.Schematic) records why, pointing here.

Every result carries a fixed Warning field (catalogWarning) naming siderolabs/extensions/siderolabs/overlays as catalogs and stating plainly that mirroring them does not mirror what they reference -- unconditionally, whether or not --schematic was given, since a bare --talos-version call gives no way to know whether some other cluster's schematic will need an extension this list doesn't name. Silently printing five images and nothing else is exactly the failure mode this command exists to prevent (architecture.md's own framing); the command would rather over-warn on every call than risk an operator reading five images as a complete mirror.

Consequences

• An operator whose schematic customizes extensions or overlays still has to resolve those manually today (e.g. hack/copy-artifacts.sh, which already does this by pulling the catalogs) -- ichor images list tells them this is necessary but does not do it for them.
• If Image Factory's API grows a schematic-resolving endpoint later, or running one locally against a pulled catalog becomes acceptable for this command (a deliberate scope change, not an oversight), extending buildImageList to use imagesListOptions.Schematic is additive: no existing output shape needs to change, only the Warning narrowing once resolution is possible.
• Not built here: mirror reachability pre-checks (architecture.md calls these out as a separate, later feature) and any change to hack/copy-artifacts.sh itself (not vendored into this repository).