registryMirrors cannot express overridePath / skipFallback — Harbor proxy-cache mirrors are not configurable

Start in charts/talm/templates/_helpers.tpl: the talm.guard.registries, talm.config.registries.multidoc and talm.config.registries.legacy helpers. Reproduce with talm template -f nodes/node1.yaml --offline using a registryMirrors docker.io entry that has a Harbor-style endpoint. Done means per-mirror overridePath and skipFallback render into RegistryMirrorConfig (overridePath per endpoint, skipFallback at mirror level) and into machine.registries.mirrors as siblings of endpoints, while output stays byte-identical when neither key is set. Guards should reject non-bool values, mapping endpoints, and skipFallback on pre-v1.9 contracts.

Problem statement

Talos supports overridePath on registry mirror endpoints ("use the endpoint path as supplied, without adding /v2/") and skipFallback on mirrors. overridePath is required when using Harbor (or any cache that puts the registry name in the pull path) as a pull-through cache — the endpoint URL already contains /v2 and the registry name, e.g. https://mirror.example.com/v2/proxy-docker.io, and containerd must not append /v2 again. Without it the cache answers with its HTML portal and every pull fails with unexpected media type text/html. This is a documented upstream use case: https://docs.siderolabs.com/talos/v1.14/configure-your-talos-cluster/images-container-runtime/pull-through-cache

talm's registryMirrors values knob (charts/talm/templates/_helpers.tpl: talm.guard.registries, talm.config.registries.multidoc, talm.config.registries.legacy) accepts only a plain list of endpoint URL strings per registry host and renders - url: <endpoint> (multidoc RegistryMirrorConfig) / - <endpoint> (legacy machine.registries.mirrors). There is no way to express overridePath or skipFallback.

Environment

• talm 0.35.0 (vendored github.com/siderolabs/talos/pkg/machinery v1.14.0)
• preset cozystack, templateOptions.talosVersion: "v1.12" (the preset default contract)
• Verified identical on current main (b08c591).

Minimal reproduction (offline)

talm init --preset cozystack --name repro
printf '# talm: nodes=["192.0.2.4"], endpoints=["192.0.2.4"], templates=["templates/controlplane.yaml"]\n' > nodes/node1.yaml
# values.yaml: set endpoint, advertisedSubnets, and
#   registryMirrors:
#     docker.io:
#       endpoints: ["https://mirror.example.com/v2/proxy-docker.io"]
talm template -f nodes/node1.yaml --offline

1. Baseline renders, but the knob cannot express the flag. Output contains:

   apiVersion: v1alpha1
   kind: RegistryMirrorConfig
   name: docker.io
   endpoints:
     - url: https://mirror.example.com/v2/proxy-docker.io
   

   No overridePath — the node will append /v2 and Harbor-style caches fail.

2. Trying to force the flag via map-form endpoints fails at the chart guard (any contract; this is chart-level, before any Talos decode):

   registryMirrors:
     docker.io:
       endpoints:
         - url: https://mirror.example.com/v2/proxy-docker.io
           overridePath: true
   

   failed to render templates: rendering chart: execution error at (repro/templates/worker.yaml:2:4):
   talm: registryMirrors.docker.io endpoint "map[overridePath:true url:https://mirror.example.com/v2/proxy-docker.io]" has no scheme.
   Talos rejects it with "unsupported scheme"; write the full URL, e.g. https://map[overridePath:true url:...].
   

3. A hand-written RegistryMirrorConfig carrying overridePath passes talm's own strict decode at every contract (v1.12, v1.13) — the gap is purely the chart knob, not the engine:

   # templates/override.yaml
   apiVersion: v1alpha1
   kind: RegistryMirrorConfig
   name: docker.io
   skipFallback: true
   endpoints:
     - url: https://mirror.example.com/v2/proxy-docker.io
       overridePath: true
   

   Rendered via a modeline-only node file:

   printf '# talm: nodes=["192.0.2.4"], endpoints=["192.0.2.4"], templates=["templates/override.yaml"]\n' > nodes/override.yaml
   talm template -f nodes/override.yaml --offline                    # preset default contract (v1.12)
   talm template -f nodes/override.yaml --offline --talos-version v1.13
   

   Both render cleanly with no decode warning. Control experiment: adding an actually-unknown key (bogusKey: true) to the same document trips the strict decoder inside the render (warning: could not load the rendered config for the v1alpha1 conflict check: error decoding document v1alpha1/RegistryMirrorConfig/docker.io ...: unknown keys found during decoding: endpoints: - bogusKey: true), proving overridePath/skipFallback are known to the vendored machinery (they exist in cri.RegistryMirrorConfig since machinery v1.12 and in legacy machine.registries.mirrors since v1.3 / v1.9 respectively).

Expected behavior

registryMirrors should let each mirror carry overridePath (and skipFallback), rendered into both schemas the charts emit:

• multidoc: overridePath per endpoint, skipFallback at mirror level (the only shapes RegistryMirrorConfig has);
• legacy: both as siblings of endpoints under machine.registries.mirrors.<name> (the only shape the legacy schema has).

Proposed schema

Per-mirror keys, mirroring the legacy Talos schema:

registryMirrors:
  docker.io:
    endpoints: ["https://mirror.example.com/v2/proxy-docker.io"]
    overridePath: true
    skipFallback: true

Chosen over map-form endpoints (endpoints: [{url, overridePath}]) because the legacy schema has no per-endpoint form — a per-endpoint values shape could not render there, and the knob is documented as keeping one values file portable across both schemas and presets. On the multidoc schema overridePath is stamped onto every endpoint of the mirror; all endpoints of one mirror share the same path layout in practice. Backward compatible: with neither key set, rendered output is byte-identical to today; string-list endpoints are unchanged. Guards fail fast on non-bool values, on mapping endpoints (with a message naming the per-mirror shape), and on skipFallback pinned to a pre-v1.9 contract.

A PR implementing exactly this (chart-only; guards, both emission paths, preset values.yaml docs, contract tests) follows.

Related TLS gotcha (informational — no talm change needed)

One neighboring trap worth a sentence for anyone landing here: Talos writes the per-endpoint CA from RegistryTLSConfig/registryTLS into the containerd hosts.toml entry for that endpoint host (internal/pkg/containers/cri/containerd/hosts.go, configureEndpoint). containerd's docker resolver then performs the token/auth realm request with the HTTP client built from that hosts entry — including its TLS configuration — so when the realm lives on a different host whose certificate chain is not covered, the token fetch can fail with an x509 error even though the mirror itself is reachable. We observed this with a registry endpoint pinned to a private CA whose token realm was served by a different host. The workaround that solved it for us is a TrustedRootsConfig document (machinery config/types/security/trusted_roots.go, available since Talos v1.8) that adds the private CA to the node-wide trust store instead of pinning it per registry endpoint — this can already be shipped today as an extra document in a node body or template, so it needs no talm change. Mentioning it here because it is the next thing an operator hits after adopting a Harbor proxy cache with a private CA; it is containerd/Talos behavior, not a talm bug.