# 0012. Mirroring the volume config document kinds for disk roles

Status: Accepted · Date: 2026-10-25 · Design section: 4.4 (Typed configuration), ### Nodes

Decided: Mirror `VolumeConfig`/`UserVolumeConfig`/`RawVolumeConfig` as three more mirrorgen roots, for disk roles

## Context

Phase 3 (disk roles, `### Nodes` in `docs/design/architecture.md`) assigns each disk a role:
`system` (install target plus EPHEMERAL), `ephemeral` (EPHEMERAL on its own disk), `storage`
(handed to a storage preset via a CSI provisioner), `userVolume`, or `unused`. `system` is
already representable — it is `machine.install`, a `v1alpha1.Config` field already on the
mirror allow-list. The other four roles are not: Talos expresses them as separate, modern
config document kinds — `VolumeConfig`, `UserVolumeConfig`, `RawVolumeConfig` — none of which
were on mirrorgen's allow-list. So, as the design already says, disk roles begin with generator
work, not controller work; this ADR is that first step.

## Decision

Add three roots to `internal/tools/mirrorgen/main.go`'s `roots`:
`block.VolumeConfigV1Alpha1` (kind `VolumeConfig`), `block.UserVolumeConfigV1Alpha1`
(kind `UserVolumeConfig`), `block.RawVolumeConfigV1Alpha1` (kind `RawVolumeConfig`), all from
`github.com/siderolabs/talos/pkg/machinery/config/types/block`. `VolumeConfig` covers `ephemeral`
(and, in principle, a non-default `system` disk layout); `UserVolumeConfig` covers `userVolume`;
`RawVolumeConfig` covers `storage` — its own doc comment says it is "intended to be used with CSI
provisioners," which is exactly what a storage preset is. `unused` needs no document at all: the
absence of an assignment is the representation.

`VolumeConfig.MetaName` (which system volume this document configures) mirrors as a plain,
unrestricted `string` — Talos's own type carries no enum here either, since `VolumeConfig` also
names volumes phase 2 never touches. **Both `STATE` and `EPHEMERAL` are representable**, the same
way, through the same field; `TestRoundTripVolumeConfig` exercises it with `EPHEMERAL` (the role
the design calls out), and nothing about the mechanism is specific to that name.

Walking these three surfaced the same two kinds of problem ADR 0003 already has tables for, plus
one the generator didn't have a table for yet:

- **Six more type-keyed substitutions**, added to `substTable`: `cel.Expression` (the disk
  selector's type — a compiled CEL AST, no exported fields, behind `TextMarshaler`, exactly
  `ByteSize`'s shape from ADR 0003's original spike); `block.Size` and `block.ByteSize`
  (private-field structs behind `TextMarshaler`, used for `minSize`/`maxSize`); and three
  `int`-backed enums with a `TextMarshaler` of their own (`block.VolumeType`,
  `block.FilesystemType`, `block.EncryptionProviderType` — all from the *separate*
  `resources/block` package, not `config/types/block`, which happens to share its bare package
  name). The enums are a judgment call rather than a hard requirement: the generic path would
  mirror them as a bare `int` and still round-trip correctly, but the CRD would then show a raw
  ordinal (`type: 2`) instead of the name Talos itself uses (`type: xfs`) — inconsistent with
  `InstallDiskType`, already mirrored as a string, and genuinely confusing in a user-facing
  field.
- **One more secret field**, added to `secretFields`: `EncryptionKey.KeyStatic`, a disk
  encryption passphrase embedded directly in the document. Talos's own `EncryptionSpec.Redact`
  method targets this exact field for the same reason Ichor drops it. The *whole* `static` key
  source is dropped, not just its one `passphrase` field, because an empty `static: {}` left
  behind would be unusable and only confusing — there would be no way to say what the key
  actually is. KMS, TPM and node-ID key sources carry no secret (an endpoint URL, hardware-sealed,
  or derived) and stay. One table entry drops it from both `block.EncryptionKey` and the older,
  already-mirrored `v1alpha1.EncryptionKey` (legacy per-partition disk encryption), since both
  share the field name `KeyStatic` and the table is keyed by bare name, not by package.
- **A genuine name collision**, the first the generator has hit: `block.EncryptionKey`,
  `EncryptionKeyKMS`, `EncryptionKeyTPM` and `EncryptionKeyNodeID` all share a bare name with an
  existing, unrelated mirror struct generated from the legacy `v1alpha1.EncryptionKey` family
  (older, per-partition disk encryption, already mirrored via `v1alpha1.Config`). Mirror struct
  names are one flat Go namespace (`zz_generated.mirror.go`), so this is a real conflict, not a
  type-keyed or field-keyed question the existing tables could resolve. A new, small table,
  `typeRenames` (qualified machinery type name → mirror name), disambiguates it: the four
  `block`-sourced types take a `Volume` prefix; the already-established `v1alpha1` names are left
  alone. `structDef` gained a `machName` field (distinct from the possibly-renamed mirror `name`)
  so the generated conversion code still calls the real machinery type regardless of the rename.
  `EncryptionKeyStatic` itself never needed a rename: dropping `EncryptionKey.KeyStatic` means it
  is never reached in either package.

`TalosConfigPatchDocument` (`api/v1alpha1/talosconfigpatch_types.go`) gained one optional field
per new kind (`volumeConfig`, `userVolumeConfig`, `rawVolumeConfig`), three more names in the
`kind` enum, and the matching three terms in both CEL rules (exactly-one-populated,
kind-matches-field) — the same shape phase 2's three existing kinds already use.

## What the fallback chain can and can't express

The disk selector (`ProvisioningSpec.diskSelector.match`) is the one field this whole phase
turns on, since it is how a volume document says which disk it means. It mirrors as a plain
string carrying an arbitrary CEL expression, exactly like every other substTable entry: Ichor
carries the text, Talos defines what is inside it. That matters here specifically because
architecture.md's fallback chain (WWID → serial → by-id path → bus path) is not a schema Ichor
has to model — it is just a choice of which fields on Talos's own `disk.*` CEL variable (a
`block.DiskSpec` protobuf: `wwid`, `serial`, `symlinks` for by-id-style udev links, `bus_path`,
`transport`, `rotational`, `size`, …) a given expression happens to reference, and the string
field carries any of them unchanged.
`TestRoundTripVolumeConfig` also round-trips a *negative* `maxSize` (`"-10GiB"`), confirming the
reserve-free-space meaning architecture.md documents survives the mirror, not just the common
positive case.

Nothing about the three new kinds turned out to be unrepresentable. The things phase 3 still
can't do are a different kind of gap, not a mirroring one, and out of this change's scope on
purpose:

- **User volumes and EPHEMERAL sharing one disk** (including what a negative `maxSize` means in
  that combination) is still an open question — `docs/design/architecture.md`'s Open questions,
  unchanged by this ADR. It needs a design decision, not a generator fix.
- **Actually applying a disk role to a node** — the reconciler that turns a `TalosMachine`'s
  approved disk roles into these documents — is `internal/controller/`, untouched here.
- **A changed selector silently doing nothing**, and a **lowered `maxSize` being silently
  ignored** (both documented in architecture.md, verified against Talos's volume manager) are
  behaviors of the *running* system, not of the CRD schema; detecting and reporting them is
  reconciler work.

## Measured: served CRD size

Same methodology as ADR 0003's follow-up: a real envtest apiserver, a raw GET on the
`CustomResourceDefinition` object itself. `talosconfigpatches` was 81,965 bytes served (5.2% of
etcd's 1,572,864-byte `--max-request-bytes` ceiling) before this change. With the three volume
kinds added, it is **96,792 bytes served, 6.2% of the ceiling** (210,130 bytes on disk). Headroom
remains in no way the constraint — the three new kinds added about 15 KB served between them,
and there is room for the rest of Talos's modern document kinds many times over.

## Follow-up: pkg/fieldmeta rules for the three new kinds

Making the three kinds representable means a user can now write a path `pkg/fieldmeta` has no
rule for, which would silently fall through to its reboot-required default. The default being
*safe* does not make it *correct*: the dangerous direction is an install-time-only field left at
reboot-required, since a reboot that cannot possibly take effect gets re-detected as drift and
rebooted again -- a loop. The safe-but-wasteful direction is a live-safe field left at
reboot-required: an unneeded reboot, not a loop, since the reboot (if performed) still leaves the
node converged with the rendered config afterwards.

**Verified, not guessed, and cited:**

- Talos's own documented no-reboot allow-list (`docs.siderolabs.com`, "Edit Machine
  Configuration" guide, v1.13) lists exact config paths (`.machine.network`, `.machine.kubelet`,
  `.cluster`, …) that a no-reboot apply accepts; it says plainly that anything outside that list
  makes a no-reboot apply "fail[] if the change contains any fields that can not be updated
  without a reboot." None of `VolumeConfig`, `UserVolumeConfig` or `RawVolumeConfig` appear on it
  at all. That alone rules out marking any of their paths `safe`.
- Talos's own volume manager
  (`internal/app/machined/pkg/controllers/block/volume_manager.go`'s `processVolumeConfig`) runs
  a state machine per volume: `Missing`/`Waiting` → `LocateAndProvision` (consults the disk
  selector) → `Located` → `Grow` → `Provisioned` → `HandleEncryption` → `Prepared` → `Format` →
  `Ready`, where `Ready` does nothing further. The disk selector and the grow step are only ever
  reached on the way to a volume's *first* `Ready`; nothing re-enters that path afterwards. This
  directly confirms, for all three kinds (the state machine is shared, not system-volume-specific
  -- see `internal/.../volumeconfig/user_volumes.go`'s `UserVolumeTransformer`, which feeds the
  same `VolumeConfig` resource type), the behavior architecture.md already documents for
  `EPHEMERAL` specifically: a selector change on an already-provisioned volume does nothing.
- `internal/controller/talosmachine_controller.go` (read, not modified — out of scope) was read to
  check the loop concern directly: its `switch` on `impact` handles `InstallTimeOnly` *before*
  `RebootRequired`, and that case returns through `r.ready(...)` with `ConditionFalse` and a
  "needs a reset and reinstall" message — it never calls `r.refuseReboot` (the only path that
  actually reboots a node). **Confirmed: an install-time-only classification cannot cause a
  reboot loop**, here or for any existing rule; it is purely reported.

**Classified, with the reasoning above:** `VolumeConfig.provisioning` (disk selector, min/max
size, grow) is `installTimeOnly` — the same classification `machine.install` already has, for the
matching reason architecture.md gives: changing which disk a system volume lives on is a
reset-and-reinstall operation. This is the only new rule added.

**Deliberately left at the reboot-required default, because it was not verified rather than
because it was verified safe:**

- `VolumeConfig.filesystem`, `.encryption` and `.mount`. The same state machine gates `Format` and
  `HandleEncryption` the same way it gates provisioning, which is suggestive, but changing
  encryption or filesystem settings is consequential enough that a suggestive read did not seem
  like enough to act on within this change.
- `VolumeConfig.trim` and `.scrub`. These are read by their own continuously-scheduled
  controllers (`volume_trim.go`, `fs_scrub.go`), outside the provisioning state machine entirely,
  which argues for `safe` — but that is inference from a different controller's shape, not a
  statement this change found anywhere, so it stays at the default too.
- Any `UserVolumeConfig` or `RawVolumeConfig` path. Architecture.md states that assigning
  `storage` or `userVolume` to a previously unused disk does *not* need a reset, which rules out
  `installTimeOnly`; the no-reboot allow-list finding above rules out `safe`. Reboot-required is
  each kind's correct classification by elimination, needing no rule at all —
  `TestAssess_UserAndRawVolumeConfigStayRebootRequired` pins this so a future change does not
  "fix" it into something wrong.

**`Unsupported` was considered for the maxSize-shrink case and rejected.** Architecture.md records
that a *lowered* `maxSize` on an existing volume is silently ignored (partitions only ever grow) —
a real gap, but not one `Impact.Unsupported` can hold without changing its meaning:
`Unsupported` is specifically "needs a newer Talos version than the cluster's pinned contract"
(`Assess`'s own doc comment, and every existing use of it), a per-*path*, version-gated question.
Whether a `maxSize` change is a no-op is a per-*value* question — the same shrink value is a no-op
on an existing volume and a perfectly normal initial size on a brand-new one — and `Assess` only
ever sees changed paths, never old/new values or whether the volume already exists. Overloading
`Unsupported` (or `RebootRequired`, or a new field) to mean "this specific value won't do what you
asked" would conflate two different failure modes behind one boolean, which is the kind of
silent-wrongness this project otherwise tries hard to avoid. The gap stays exactly where
architecture.md already put it: a controller-side detection problem ("Ichor has to detect that
itself and report 'accepted, no effect'"), explicitly out of this change's scope
(`internal/controller/` untouched). `Impact`'s three fields were sufficient for what this change
needed to express; no fourth field or new axis was added.

## Consequences

- Disk roles have a typed, schema-validated representation for everything except the
  `system`/install-target role, which already had one. The reconciler and CLI work phase 3 still
  needs can build on `documents[]` the same way phase 2's kinds already do.
- `typeRenames` and `machName` are small, general additions (not special-cased to these three
  kinds), so the next genuine name collision — and there will eventually be one, since Talos's
  document kinds are not designed with a single flat Go namespace in mind — has a place to go
  without new generator machinery.
- `secretFields` now has ten entries instead of nine, and the pattern (one entry, keyed by bare
  struct/field name, catches the same field across unrelated machinery types) held up on its
  second use.