0004. Phase 1 creates three kinds, not seven

Status: Accepted · Date: 2026-10-25 · Design section: 4.1, 4.2, roadmap item 1

Decided: Phase 1 scaffolds only TalosCluster, TalosMachine and TalosConfigPatch, with no controllers yet

Context

The API table lists seven kinds. Roadmap item 1 asks for "CRDs and the kubebuilder project, Helm chart and Kustomize base, deletion protection, e2e scaffolding", without saying which kinds, and the phase ordering puts TalosEtcdBackup in phase 5, TalosOperation and IchorInstallation in phase 6 and TalosStorage in phase 7.

Creating a kind costs one kubebuilder create api call and is additive, so nothing is saved by creating all seven now. Guessing their fields is what costs: anything published in v1alpha1 has to keep working, and a field no code reads yet is a field whose shape nothing has tested.

Decision

Phase 1 creates the three kinds the next two phases actually work on — TalosCluster, TalosMachine, TalosConfigPatch — with --resource=true --controller=false, since reconcilers are phase 2. TalosStorage, TalosEtcdBackup, TalosOperation and IchorInstallation are created in the phase that gives them behaviour.

Within those three, phase 1 defines only the fields phases 1 to 3 need. Later phases add their own, which is backwards compatible within v1alpha1. Deferred for now: documents[] and defaultsRule (phase 2 and 3, see ADR 0003), disks[] / systemDiskLayout / forceRemove / upgradeHold (phase 3), cni and gitops (phase 4), upgradeStrategy (phase 6), monitoring / components[] / integrations[] (phase 9), images (phase 10).

Three field-level decisions that the design leaves open:

• versionContract is required, not defaulted. Principle 4 pins the version contract in the CR so that a machinery bump cannot change what gets applied. If the field were optional and resolved at reconcile time, a bump would do exactly that. Requiring it needs no webhook; a defaulting webhook that fills it from talosVersion at creation can relax this later without breaking anyone.
• TalosMachine.spec.nodeLabels, not labels. The design calls it labels; inside a spec that reads as "labels on this object", when what is meant is labels to put on the Kubernetes Node.
• layer cannot be set to system. The system layer is generated by Ichor, so the enum offers cluster, role, selector and machine only, and the schema rejects the rest rather than a webhook having to.

Consequences

• Phase 1 ships a small, complete API instead of a large, speculative one, and the chart's CRD set grows one kind at a time as the phases land.

• A kind's fields get designed next to the code that reads them, so the acceptance criteria for each phase can actually check the shape.

• The cost is that kubectl get crd won't show the full catalogue until phase 7. The API table in the design doc remains the place to see where it's going.

• Update: IchorInstallation was created in phase 6 with ADR 0059.