From 84d642655c4cbc3dd9b030261470b22992d95ff2 Mon Sep 17 00:00:00 2001 From: Mateusz Urbanek Date: Thu, 9 Jul 2026 18:27:16 +0200 Subject: [PATCH] docs: add RAID and unattended install pages for v1.14 Document RAIDArrayConfig (RAID1 provisioning, bootable arrays, user volumes, inspection) and UnattendedInstallConfig (disk selection, wipe and reboot behavior, status phases). Signed-off-by: Mateusz Urbanek --- .../unattended-install.mdx | 133 +++++++++++++ .../storage-and-disk-management/raid.mdx | 184 ++++++++++++++++++ talos-v1.14.yaml | 2 + 3 files changed, 319 insertions(+) create mode 100644 public/talos/v1.14/configure-your-talos-cluster/lifecycle-management/unattended-install.mdx create mode 100644 public/talos/v1.14/configure-your-talos-cluster/storage-and-disk-management/raid.mdx diff --git a/public/talos/v1.14/configure-your-talos-cluster/lifecycle-management/unattended-install.mdx b/public/talos/v1.14/configure-your-talos-cluster/lifecycle-management/unattended-install.mdx new file mode 100644 index 00000000..3f63bbf6 --- /dev/null +++ b/public/talos/v1.14/configure-your-talos-cluster/lifecycle-management/unattended-install.mdx @@ -0,0 +1,133 @@ +--- +title: "Unattended Install" +description: "Install Talos declaratively from machine configuration." +weight: 35 +canonical: https://docs.siderolabs.com/talos/v1.14/configure-your-talos-cluster/lifecycle-management/unattended-install +--- + +import { VersionWarningBanner } from "/snippets/version-warning-banner.jsx" + + + +Talos Linux can install itself to disk from a multi-document machine configuration by using `UnattendedInstallConfig`. +Use unattended install when a node boots from an ISO, PXE, iPXE, or another ephemeral boot asset and should install to a selected local disk without invoking the installer manually. + +`UnattendedInstallConfig` replaces the deprecated `.machine.install` field for new configurations. +It is especially useful with Image Factory assets and custom installer images that include system extensions. + +## Configure unattended install + +Add an `UnattendedInstallConfig` document to the machine configuration. +The following example installs Talos to the disk whose stable path is `/dev/sda`: + +```yaml +apiVersion: v1alpha1 +kind: UnattendedInstallConfig +installer: + image: factory.talos.dev/metal-installer/: +provisioning: + diskSelector: + match: disk.dev_path == "/dev/sda" + wipe: true +``` + +The `provisioning.diskSelector.match` field is a CEL expression evaluated against discovered disks as `disk`. +Use a selector that matches exactly one intended install target. +For production configurations, prefer stable disk properties such as `disk.serial`, `disk.wwid`, or `disk.symlinks` instead of `/dev/sd*` names when possible. + +Inspect the disks reported by the node before choosing a selector: + +```bash +talosctl --nodes get disks -o yaml +``` + +Apply the configuration patch while the node is running from the ephemeral boot media: + +```bash +talosctl --nodes patch mc --patch @unattended-install.patch.yaml +``` + +After the configuration is applied, Talos waits for disks to be discovered, selects the first matching disk, runs the installer container, and records progress in `UnattendedInstallStatus`. +If multiple disks match, Talos logs a warning and uses the first match. + +## Installer image + +Set `installer.image` to the installer image you want the node to write to disk. +Use the Image Factory installer image for the same schematic as the boot asset when the installed system needs the same system extensions or other image customizations: + +```yaml +apiVersion: v1alpha1 +kind: UnattendedInstallConfig +installer: + image: factory.talos.dev/metal-installer/:v1.14.0 +provisioning: + diskSelector: + match: '"/dev/disk/by-id/nvme-SAMSUNG_MZQL21T9" in disk.symlinks' +``` + +If `installer.image` is omitted, Talos tries to derive the installer image from the Image Factory boot entry and the current schematic. +This requires booting from an Image Factory asset. +Set `installer.image` explicitly for non-Image Factory boot assets or when installing a custom installer image. + +## Wipe behavior + +By default, Talos wipes the target disk during installation. +Set `provisioning.wipe` to `false` only when you intentionally want to preserve existing partition data that the installer can reuse: + +```yaml +apiVersion: v1alpha1 +kind: UnattendedInstallConfig +installer: + image: factory.talos.dev/metal-installer/:v1.14.0 +provisioning: + diskSelector: + match: disk.serial == "S4ABC123" + wipe: false +``` + +## Reboot behavior + +The optional `reboot` field controls what happens after a successful installation: + +- If `reboot` is not set, Talos reboots only when `installer.image` is set explicitly. +- If `reboot: true`, Talos always requests a reboot after installation. +- If `reboot: false`, Talos leaves the node running from the current boot media after installation. + +Example: + +```yaml +apiVersion: v1alpha1 +kind: UnattendedInstallConfig +reboot: true +installer: + image: factory.talos.dev/metal-installer/:v1.14.0 +provisioning: + diskSelector: + match: disk.serial == "S4ABC123" +``` + +## Inspect installation status + +Use the unattended install status resource to monitor progress: + +```bash +$ talosctl --nodes get unattendedinstallstatuses +NODE NAMESPACE TYPE ID VERSION PHASE +172.20.0.5 runtime UnattendedInstallStatus unattended-install 1 installed +``` + +Request YAML output to see the installer image and any error message: + +```bash +talosctl --nodes get unattendedinstallstatuses unattended-install -o yaml +``` + +The phase is one of: + +- `pending`: no disk currently matches the selector. +- `installing`: the installer is running. +- `installed`: installation completed and no reboot is pending. +- `waiting-for-reboot`: installation completed and Talos requested a reboot. +- `failed`: installation failed; inspect the `error` field and machine logs. + +Once a node is installed to disk, Talos reports the install as complete and does not run the unattended installer again on that boot. diff --git a/public/talos/v1.14/configure-your-talos-cluster/storage-and-disk-management/raid.mdx b/public/talos/v1.14/configure-your-talos-cluster/storage-and-disk-management/raid.mdx new file mode 100644 index 00000000..a6723550 --- /dev/null +++ b/public/talos/v1.14/configure-your-talos-cluster/storage-and-disk-management/raid.mdx @@ -0,0 +1,184 @@ +--- +title: "RAID" +description: "Provision and inspect Linux MD RAID arrays." +weight: 40 +canonical: https://docs.siderolabs.com/talos/v1.14/configure-your-talos-cluster/storage-and-disk-management/raid +--- + +import { VersionWarningBanner } from "/snippets/version-warning-banner.jsx" + + + +Talos Linux can declaratively provision Linux MD software RAID arrays with `RAIDArrayConfig`. +In Talos v1.14, `RAIDArrayConfig` supports RAID1 arrays. +The resulting array is exposed through a stable by-id path and can be used as an install target, as a block device for user volumes, or by another storage stack. + +Talos reconciles RAID from machine configuration documents: + +- `RAIDArrayConfig` selects member disks or partitions and creates or extends an MD array. +- `MDArraySpec` records the desired state derived from configuration. +- `MDArrayStatus` reports the observed array device, members, sync state, and errors. + +## Provision a RAID1 array + +The following example creates a RAID1 array named `data` from NVMe disks larger than 100 GiB: + +```yaml +apiVersion: v1alpha1 +kind: RAIDArrayConfig +name: data +level: raid1 +metadata: "1.2" +provisioning: + volumeSelector: + match: disk.transport == "nvme" && disk.size > 100u * GiB +``` + +Apply the configuration patch to the node: + +```bash +talosctl --nodes patch mc --patch @raid.patch.yaml +``` + +The volume selector is a CEL expression evaluated against each discovered volume as `volume`. +For whole disks, the expression can also use the `disk` variable. +The system disk and its partitions are never eligible as members of a data array. + +Use selectors that match only the intended member devices. +For production configurations, prefer stable disk identifiers such as serial number, WWID, or symlink over `/dev/sd*` names: + +```bash +talosctl --nodes get disks -o yaml +talosctl --nodes get discoveredvolumes -o yaml +``` + +Talos exposes the array at a stable MD by-id path. +For the example above, the stable device path is `/dev/disk/by-id/md-name-talos:data`. + +## Configure RAIDArrayConfig + +A `RAIDArrayConfig` document requires: + +- `name`: the array name, 1-32 characters, using ASCII letters, digits, hyphens, and underscores. +- `level`: the RAID level. Talos v1.14 supports `raid1`. +- `provisioning.volumeSelector.match`: a CEL expression selecting member disks or partitions. + +Optional fields: + +- `metadata`: MD metadata format, either `"1.0"` or `"1.2"`. + The default is `"1.0"`, which stores metadata at the end of each member and is suitable for bootable arrays. + Use `"1.2"` for data arrays that do not need to be bootable. + +Provisioning is additive. +Talos creates the array when enough members match the selector and adds matching members to an existing array, but it does not remove members or destroy arrays just because the configuration changes. +Remove arrays explicitly with `talosctl wipe md`. + +In Talos v1.14 there is no way to shrink an array or remove a failed member device through machine configuration or `talosctl`. +Narrowing the selector or dropping a member from it does not detach that member, and a failed disk cannot be replaced in place. +The only supported destructive operation is `talosctl wipe md`, which stops the whole array and clears every member. +To recover from a failed member, wipe the array and provision it again or use alternative means (e.g. `talosctl debug`). + +## Boot from a RAID1 array + +Talos can install and boot from an MD RAID1 array. +This is useful when the Talos system disk itself should be mirrored. + +A bootable RAID setup needs: + +- A `RAIDArrayConfig` using `level: raid1` and `metadata: "1.0"`. +- An `UnattendedInstallConfig` that selects the MD array as the install disk. +- The `raid1` kernel module available during boot. + +Example patch: + +```yaml +apiVersion: v1alpha1 +kind: RAIDArrayConfig +name: boot +level: raid1 +metadata: "1.0" +provisioning: + volumeSelector: + match: disk.transport == "nvme" && disk.size >= 100u * GiB +--- +apiVersion: v1alpha1 +kind: UnattendedInstallConfig +provisioning: + diskSelector: + match: '"/dev/disk/by-id/md-name-talos:boot" in disk.symlinks' +--- +apiVersion: v1alpha1 +kind: KernelModuleConfig +name: raid1 +``` + +Boot the node from an ephemeral Talos asset that contains this configuration. +Talos creates the RAID1 array, waits for the MD device to appear, and the unattended installer writes Talos to the array selected by `/dev/disk/by-id/md-name-talos:boot`. +For details on the installer document, see [Unattended Install](../lifecycle-management/unattended-install). + +For boot arrays, use metadata `"1.0"`. +Metadata `"1.2"` places the MD superblock near the beginning of the device and is intended for non-boot data arrays. + +## Use RAID with user volumes + +A RAID array can back a Talos user volume by selecting the MD device as the volume disk. +For example, after creating an array named `data`, create a user volume from the array device: + +```yaml +apiVersion: v1alpha1 +kind: UserVolumeConfig +name: local-storage +provisioning: + diskSelector: + match: '"/dev/disk/by-id/md-name-talos:data" in disk.symlinks' + minSize: 100GiB + maxSize: 100GiB +``` + +Configure the consumer of the user volume separately. +For details, see [User Volumes](./disk-management/user). + +## Inspect RAID state + +Inspect the desired RAID specs and observed array status: + +```bash +talosctl --nodes get mdarrayspecs +talosctl --nodes get mdarraystatuses +``` + +Example status output: + +```bash +$ talosctl --nodes get mdarraystatuses +NODE NAMESPACE TYPE ID VERSION LEVEL STATUS SYNC DEVICE +172.20.0.5 storage MDArrayStatus data 1 raid1 rebuilding resync /dev/disk/by-id/md-name-talos:data +``` + +Request YAML output to see member devices, the MD UUID, metadata version, array state, sync action, and any provisioning error: + +```bash +talosctl --nodes get mdarraystatuses data -o yaml +``` + +Status values include: + +- `unknown`: Talos has not yet determined the array state. +- `waiting`: Talos is waiting for enough matching members. +- `rebuilding`: the array exists and is syncing or rebuilding. +- `ready`: the array exists and is in the expected state. +- `error`: provisioning failed; inspect the `error` field. + +## Remove a RAID array + +First remove the `RAIDArrayConfig` document from the machine configuration. +If the document remains in configuration, Talos will reconcile the array again. + +Then wipe the array with `talosctl wipe md`: + +```bash +talosctl --nodes wipe md /dev/disk/by-id/md-name-talos:data +``` + +This command stops the MD array and clears the superblock on each member device. +It is destructive, and the array must not be mounted or claimed by another device. diff --git a/talos-v1.14.yaml b/talos-v1.14.yaml index 1448dfc8..08931b23 100644 --- a/talos-v1.14.yaml +++ b/talos-v1.14.yaml @@ -207,6 +207,7 @@ navigation: - "storage-and-disk-management/disk-management/system" - "storage-and-disk-management/disk-management/user" - "storage-and-disk-management/lvm" + - "storage-and-disk-management/raid" - "storage-and-disk-management/disk-encryption" - "storage-and-disk-management/swap" - group: "Logging & Telemetry" @@ -221,6 +222,7 @@ navigation: - group: "Lifecycle Management" pages: - "lifecycle-management/upgrading-talos" + - "lifecycle-management/unattended-install" - "lifecycle-management/resetting-a-machine" - group: "Advanced guides"