Block Storage Configuration

Talos Linux provides sophisticated block storage configuration through dedicated document types. These replace the deprecated machine.disks and machine.systemDiskEncryption fields from v1alpha1.

UserVolumeConfig

The UserVolumeConfig document defines user-managed volumes that are automatically provisioned and mounted under /var/mnt/<name>.

Document Structure

kind: UserVolumeConfig
apiVersion: v1alpha1
metadata:
  name: volume-name

Volume Configuration

name

string

required

Name of the volume (1-34 characters). Can contain lowercase/uppercase ASCII letters, digits, and hyphens.The partition label is automatically generated as u-<name>.

volumeType

string

default:"partition"

Type of volume to create.Available types:

partition - Create a partition on a disk (default)
disk - Use an entire disk
directory - Create a directory in the system partition

volumeType: partition

Provisioning Configuration

provisioning

object

Describes how the volume is provisioned (not applicable for directory type).

Show Provisioning Options

provisioning.diskSelector

object

required

Select which disk to use for provisioning.

Show Disk Selector

provisioning.diskSelector.match

string

CEL expression to match disks. Use disk properties like transport, size, model, etc.

provisioning:
  diskSelector:
    match: 'disk.transport == "nvme"'

provisioning:
  diskSelector:
    match: 'disk.size >= 500u * GB && disk.type == "ssd"'

provisioning.minSize

string

Minimum size for the partition (supports units like GiB, GB).

provisioning:
  minSize: 10GiB

provisioning.maxSize

string

Maximum size for the partition. If not specified, uses all available space.

provisioning:
  maxSize: 50GiB

provisioning.grow

boolean

default:"false"

Automatically grow the partition to fill available space on subsequent boots.

Filesystem Configuration

filesystem

object

Describes how the volume is formatted.

Show Filesystem Options

filesystem.type

string

default:"xfs"

Filesystem type to create.Available types:

xfs (default) - XFS filesystem
ext4 - ext4 filesystem

filesystem:
  type: xfs

filesystem.projectQuotaSupport

boolean

Enable project quota support (XFS only).Note: Changing this may require a full remount.

filesystem:
  type: xfs
  projectQuotaSupport: true

Encryption Configuration

encryption

object

Describes how the volume is encrypted.

Show Encryption Options

encryption.provider

string

required

Encryption provider to use.Available providers:

luks2 - LUKS2 encryption

encryption:
  provider: luks2

encryption.keys

array

required

Encryption keys generation and storage methods. Multiple keys can be configured in different slots.

Show Key Configuration

encryption.keys[].slot

integer

required

Key slot number for LUKS2 (0-7).

encryption.keys[].static

object

Static passphrase key stored in configuration.

encryption:
  provider: luks2
  keys:
    - slot: 0
      static:
        passphrase: my-secret-passphrase

encryption.keys[].nodeID

object

Deterministically generated key from node UUID and partition label.

encryption:
  keys:
    - slot: 0
      nodeID: {}

encryption.keys[].tpm

object

TPM-based disk encryption.

encryption:
  keys:
    - slot: 0
      tpm:
        checkSecurebootStatusOnEnroll: true

Show TPM Options

encryption.keys[].tpm.options

object

TPM key protection options.

encryption.keys[].tpm.options.pcrs

array

List of PCR indices to bind the key to. Defaults to PCR 7 if not set.

tpm:
  options:
    pcrs: [7, 12]

encryption.keys[].tpm.checkSecurebootStatusOnEnroll

boolean

Verify Secure Boot is enabled during key enrollment.

encryption.keys[].kms

object

KMS-managed encryption key.

encryption:
  keys:
    - slot: 0
      kms:
        endpoint: https://kms.example.com:4443

encryption.keys[].lockToState

boolean

Lock the encryption key to random salt in STATE partition. Prevents volume unlock if STATE is compromised. Recommended with TPM encryption.

encryption.cipher

string

Cipher to use for encryption (provider-dependent).Available ciphers:

aes-xts-plain64
xchacha12,aes-adiantum-plain64
xchacha20,aes-adiantum-plain64

encryption:
  cipher: aes-xts-plain64

encryption.keySize

integer

Encryption key length in bits.

encryption.blockSize

integer

Encryption sector size.

encryption:
  blockSize: 4096

encryption.options

array

Additional --perf parameters for LUKS2.Available options:

no_read_workqueue
no_write_workqueue
same_cpu_crypt

encryption:
  options:
    - no_read_workqueue
    - no_write_workqueue

Mount Configuration

mount

object

Additional mount options for the volume.

Show Mount Options

mount.disableAccessTime

boolean

Disable file access time updates (noatime).

mount:
  disableAccessTime: true

mount.secure

boolean

default:"true"

Enable secure mount options (nosuid, nodev). Defaults to true for better security.

mount:
  secure: true

Complete Examples

kind: UserVolumeConfig
apiVersion: v1alpha1
name: local-data
volumeType: partition
provisioning:
  diskSelector:
    match: 'disk.transport == "nvme"'
  maxSize: 50GiB
filesystem:
  type: xfs
encryption:
  provider: luks2
  keys:
    - slot: 0
      tpm: {}
    - slot: 1
      static:
        passphrase: topsecret

ExistingVolumeConfig

The ExistingVolumeConfig document mounts existing volumes that were created outside of Talos.

kind: ExistingVolumeConfig
apiVersion: v1alpha1
name: data
volumeLocator:
  partitionLabel: DATA
mountpoint: /var/mnt/data

RawVolumeConfig

The RawVolumeConfig document provides raw (unformatted) volume access.

kind: RawVolumeConfig
apiVersion: v1alpha1
name: raw-storage
volumeType: partition
provisioning:
  diskSelector:
    match: 'disk.size >= 100u * GB'

SwapVolumeConfig

The SwapVolumeConfig document configures swap space.

kind: SwapVolumeConfig
apiVersion: v1alpha1
provisioning:
  diskSelector:
    match: 'disk.transport == "nvme"'
  minSize: 8GiB

VolumeConfig

The VolumeConfig document configures system volumes (EPHEMERAL, STATE, etc.).

kind: VolumeConfig
apiVersion: v1alpha1
name: EPHEMERAL
provisioning:
  grow: true
encryption:
  provider: luks2
  keys:
    - slot: 0
      tpm: {}

Disk Selector Expressions

Disk selectors use CEL (Common Expression Language) for flexible disk matching. Available disk properties:

disk.size - Disk size in bytes (use * GB or * GiB multipliers)
disk.transport - Transport type (nvme, sata, usb, etc.)
disk.type - Disk type (ssd, hdd)
disk.model - Disk model string
disk.serial - Disk serial number
disk.wwid - World-wide identifier
disk.rotational - Boolean indicating rotational media

Example Expressions

# NVMe drives only
match: 'disk.transport == "nvme"'

# SSDs larger than 500GB
match: 'disk.size >= 500u * GB && disk.type == "ssd"'

# Non-rotational drives
match: '!disk.rotational'

# Specific model
match: 'disk.model.contains("Samsung")'

# Multiple conditions
match: 'disk.transport == "nvme" && disk.size >= 1u * TB && disk.type == "ssd"'

Encryption Key Management

Key Slot Strategy

LUKS2 supports up to 8 key slots (0-7). Use multiple slots for key rotation and recovery:

Slot 0: Primary key (TPM-based for production)
Slot 1: Recovery key (static passphrase)
Slot 2: KMS-managed key (for centralized management)

TPM-Based Encryption

TPM encryption binds the key to the machine’s hardware and boot state:

encryption:
  provider: luks2
  keys:
    - slot: 0
      tpm:
        options:
          pcrs: [7]  # Secure Boot state
        checkSecurebootStatusOnEnroll: true
    - slot: 1
      static:
        passphrase: recovery-key
      lockToState: true

KMS Integration

Use external Key Management Service for centralized key management:

encryption:
  provider: luks2
  keys:
    - slot: 0
      kms:
        endpoint: https://kms.example.com:4443

Best Practices

Always Configure Recovery Keys

Include at least one static passphrase key in addition to TPM keys for recovery scenarios.

keys:
  - slot: 0
    tpm: {}
  - slot: 1
    static:
      passphrase: secure-recovery-key

Use Appropriate Volume Types

Use partition for most cases
Use disk when you need an entire dedicated disk
Use directory for lightweight storage without partitioning

Size Appropriately

Set maxSize to prevent volumes from consuming all available space. Use grow: true when you want the volume to expand.

Enable Lock to STATE

For non-STATE volumes with TPM encryption, enable lockToState for additional security.

Migration from Deprecated Fields

The following deprecated v1alpha1 fields are replaced by the new volume configuration documents:

Deprecated Field	New Document Type
`machine.disks`	`UserVolumeConfig`
`machine.systemDiskEncryption`	`VolumeConfig`

Machine Configuration

See machine-level configuration options

Network Configuration

Configure network interfaces

CLI Reference

gRPC API

Configuration API

Block Storage Configuration

UserVolumeConfig

Document Structure

Volume Configuration

Provisioning Configuration

Filesystem Configuration

Encryption Configuration

Mount Configuration

Complete Examples

ExistingVolumeConfig

RawVolumeConfig

SwapVolumeConfig

VolumeConfig

Disk Selector Expressions

Example Expressions

Encryption Key Management

Key Slot Strategy

TPM-Based Encryption

KMS Integration

Best Practices

Migration from Deprecated Fields

Machine Configuration

Network Configuration

Build docs developers (and LLMs) love

CLI Reference

gRPC API

Configuration API

​UserVolumeConfig

​Document Structure

​Volume Configuration

​Provisioning Configuration

​Filesystem Configuration

​Encryption Configuration

​Mount Configuration

​Complete Examples

​ExistingVolumeConfig

​RawVolumeConfig

​SwapVolumeConfig

​VolumeConfig

​Disk Selector Expressions

​Example Expressions

​Encryption Key Management

​Key Slot Strategy

​TPM-Based Encryption

​KMS Integration

​Best Practices

​Migration from Deprecated Fields

​Related Resources

Machine Configuration

Network Configuration

Build docs developers (and LLMs) love

UserVolumeConfig

Document Structure

Volume Configuration

Provisioning Configuration

Filesystem Configuration

Encryption Configuration

Mount Configuration

Complete Examples

ExistingVolumeConfig

RawVolumeConfig

SwapVolumeConfig

VolumeConfig

Disk Selector Expressions

Example Expressions

Encryption Key Management

Key Slot Strategy

TPM-Based Encryption

KMS Integration

Best Practices

Migration from Deprecated Fields

Related Resources