UserVolumeConfig

apiVersion: v1alpha1
kind: UserVolumeConfig
name: local-data # Name of the volume.
volumeType: directory # Volume type.

# # The encryption describes how the volume is encrypted.
# encryption:
#     provider: luks2 # Encryption provider to use for the encryption.
#     # Defines the encryption keys generation and storage method.
#     keys:
#         - slot: 0 # Key slot number for LUKS2 encryption.
#           # Key which value is stored in the configuration file.
#           static:
#             passphrase: exampleKey # Defines the static passphrase value.
#
#           # # KMS managed encryption key.
#           # kms:
#           #     endpoint: https://192.168.88.21:4443 # KMS endpoint to Seal/Unseal the key.
#         - slot: 1 # Key slot number for LUKS2 encryption.
#           # KMS managed encryption key.
#           kms:
#             endpoint: https://example-kms-endpoint.com # KMS endpoint to Seal/Unseal the key.
#     cipher: aes-xts-plain64 # Cipher to use for the encryption. Depends on the encryption provider.
#     blockSize: 4096 # Defines the encryption sector size.
#     # Additional --perf parameters for the LUKS2 encryption.
#     options:
#         - no_read_workqueue
#         - no_write_workqueue

apiVersion: v1alpha1
kind: UserVolumeConfig
name: local-data # Name of the volume.
volumeType: disk # Volume type.
# The provisioning describes how the volume is provisioned.
provisioning:
    # The disk selector expression.
    diskSelector:
        match: disk.transport == "nvme" # The Common Expression Language (CEL) expression to match the disk.

    # # The minimum size of the volume.
    # minSize: 2.5GiB

    # # The maximum size of the volume, if not specified the volume can grow to the size of the
    # maxSize: 50GiB
    # maxSize: 80%
# The filesystem describes how the volume is formatted.
filesystem:
    type: xfs # Filesystem type. Default is `xfs`.
# The encryption describes how the volume is encrypted.
encryption:
    provider: luks2 # Encryption provider to use for the encryption.
    # Defines the encryption keys generation and storage method.
    keys:
        - slot: 0 # Key slot number for LUKS2 encryption.
          # Enable TPM based disk encryption.
          tpm: {}

          # # KMS managed encryption key.
          # kms:
          #     endpoint: https://192.168.88.21:4443 # KMS endpoint to Seal/Unseal the key.
        - slot: 1 # Key slot number for LUKS2 encryption.
          # Key which value is stored in the configuration file.
          static:
            passphrase: topsecret # Defines the static passphrase value.

          # # KMS managed encryption key.
          # kms:
          #     endpoint: https://192.168.88.21:4443 # KMS endpoint to Seal/Unseal the key.

    # # Cipher to use for the encryption. Depends on the encryption provider.
    # cipher: aes-xts-plain64

    # # Defines the encryption sector size.
    # blockSize: 4096

    # # Additional --perf parameters for the LUKS2 encryption.
    # options:
    #     - no_read_workqueue
    #     - no_write_workqueue

apiVersion: v1alpha1
kind: UserVolumeConfig
name: local-data # Name of the volume.
volumeType: partition # Volume type.
# The provisioning describes how the volume is provisioned.
provisioning:
    # The disk selector expression.
    diskSelector:
        match: disk.transport == "nvme" # The Common Expression Language (CEL) expression to match the disk.
    maxSize: 50GiB # The maximum size of the volume, if not specified the volume can grow to the size of the

    # # The minimum size of the volume.
    # minSize: 2.5GiB
# The filesystem describes how the volume is formatted.
filesystem:
    type: xfs # Filesystem type. Default is `xfs`.
# The encryption describes how the volume is encrypted.
encryption:
    provider: luks2 # Encryption provider to use for the encryption.
    # Defines the encryption keys generation and storage method.
    keys:
        - slot: 0 # Key slot number for LUKS2 encryption.
          # Enable TPM based disk encryption.
          tpm: {}

          # # KMS managed encryption key.
          # kms:
          #     endpoint: https://192.168.88.21:4443 # KMS endpoint to Seal/Unseal the key.
        - slot: 1 # Key slot number for LUKS2 encryption.
          # Key which value is stored in the configuration file.
          static:
            passphrase: topsecret # Defines the static passphrase value.

          # # KMS managed encryption key.
          # kms:
          #     endpoint: https://192.168.88.21:4443 # KMS endpoint to Seal/Unseal the key.

    # # Cipher to use for the encryption. Depends on the encryption provider.
    # cipher: aes-xts-plain64

    # # Defines the encryption sector size.
    # blockSize: 4096

    # # Additional --perf parameters for the LUKS2 encryption.
    # options:
    #     - no_read_workqueue
    #     - no_write_workqueue

Field	Type	Description	Value(s)
`name`	string	Name of the volume. Name might be between 1 and 34 characters long and can only contain: lowercase and uppercase ASCII letters, digits, and hyphens.
`volumeType`	VolumeType	Volume type.	`directory` `disk` `partition`
`provisioning`	ProvisioningSpec	The provisioning describes how the volume is provisioned.
`filesystem`	FilesystemSpec	The filesystem describes how the volume is formatted.
`encryption`	EncryptionSpec	The encryption describes how the volume is encrypted.
`mount`	UserMountSpec	The mount describes additional mount options.
`trim`	TrimConfig	The trim describes the per-volume filesystem trim (fstrim) configuration.
`scrub`	ScrubConfig	The scrub describes the per-volume filesystem scrub configuration.

provisioning

ProvisioningSpec describes how the volume is provisioned.

Field	Type	Description
`diskSelector`	DiskSelector	The disk selector expression.
`grow`	bool	Should the volume grow to the size of the disk (if possible).
`minSize`	ByteSize	The minimum size of the volume. Size is specified in bytes, but can be expressed in human readable format, e.g. 100MB.
`maxSize`	Size	The maximum size of the volume, if not specified the volume can grow to the size of the disk. Size is specified in bytes or in percents. It can be expressed in human readable format, e.g. 100MB.

diskSelector

DiskSelector selects a disk for the volume.

Field	Type	Description	Value(s)
`match`	Expression	The Common Expression Language (CEL) expression to match the disk.

filesystem

FilesystemSpec configures the filesystem for the volume.

Field	Type	Description	Value(s)
`type`	FilesystemType	Filesystem type. Default is `xfs`.	`ext4` `xfs` `btrfs`
`projectQuotaSupport`	bool	Enables project quota support, valid only for ‘xfs’ filesystem. Note: changing this value might require a full remount of the filesystem.
`xfs`	XFSSpec	XFS-specific filesystem options, valid only for ‘xfs’ filesystem.

xfs

XFSSpec configures XFS-specific filesystem options.

Field	Type	Description	Value(s)
`minAllocationGroupSize`	ByteSize	The minimum size of an XFS allocation group. On non-rotational devices `mkfs.xfs` sizes the allocation group count to the number of CPUs, which on machines with many cores and a modest disk yields hundreds of tiny allocation groups. Talos bounds the allocation group size from below to keep the geometry sane; this option overrides that bound. Set to zero to use the `mkfs.xfs` defaults unchanged. Note: this only affects volumes at the time they are formatted. Size is specified in bytes, but can be expressed in human readable format, e.g. 100MB.

encryption

EncryptionSpec represents volume encryption settings.

encryption:
    provider: luks2 # Encryption provider to use for the encryption.
    # Defines the encryption keys generation and storage method.
    keys:
        - slot: 0 # Key slot number for LUKS2 encryption.
          # Key which value is stored in the configuration file.
          static:
            passphrase: exampleKey # Defines the static passphrase value.

          # # KMS managed encryption key.
          # kms:
          #     endpoint: https://192.168.88.21:4443 # KMS endpoint to Seal/Unseal the key.
        - slot: 1 # Key slot number for LUKS2 encryption.
          # KMS managed encryption key.
          kms:
            endpoint: https://example-kms-endpoint.com # KMS endpoint to Seal/Unseal the key.
    cipher: aes-xts-plain64 # Cipher to use for the encryption. Depends on the encryption provider.
    blockSize: 4096 # Defines the encryption sector size.

    # # Additional --perf parameters for the LUKS2 encryption.
    # options:
    #     - no_read_workqueue
    #     - no_write_workqueue

Field	Type	Description	Value(s)
`provider`	EncryptionProviderType	Encryption provider to use for the encryption.	`luks2`
`keys`	EncryptionKey	Defines the encryption keys generation and storage method.
`cipher`	string	Cipher to use for the encryption. Depends on the encryption provider.	`aes-xts-plain64` `xchacha12,aes-adiantum-plain64` `xchacha20,aes-adiantum-plain64`
`keySize`	uint	Defines the encryption key length.
`blockSize`	uint64	Defines the encryption sector size.
`options`	[]string	Additional —perf parameters for the LUKS2 encryption.
`allowDiscards`	bool	Allow TRIM/discard requests to be passed through to the underlying device when the encrypted volume is opened. Defaults to false.

keys[]

EncryptionKey represents configuration for disk encryption key.

Field	Type	Description
`slot`	int	Key slot number for LUKS2 encryption.
`static`	EncryptionKeyStatic	Key which value is stored in the configuration file.
`nodeID`	EncryptionKeyNodeID	Deterministically generated key from the node UUID and PartitionLabel.
`kms`	EncryptionKeyKMS	KMS managed encryption key.
`tpm`	EncryptionKeyTPM	Enable TPM based disk encryption.
`lockToState`	bool	Lock the disk encryption key to the random salt stored in the STATE partition. This is useful to prevent the volume from being unlocked if STATE partition is compromised or replaced. It is recommended to use this option with TPM disk encryption for non-STATE volumes.

static

EncryptionKeyStatic represents throw away key type.

Field	Type	Description	Value(s)
`passphrase`	string	Defines the static passphrase value.

nodeID

EncryptionKeyNodeID represents deterministically generated key from the node UUID and PartitionLabel.

kms

EncryptionKeyKMS represents a key that is generated and then sealed/unsealed by the KMS server.

encryption:
    keys:
        - kms:
            endpoint: https://192.168.88.21:4443 # KMS endpoint to Seal/Unseal the key.

Field	Type	Description	Value(s)
`endpoint`	string	KMS endpoint to Seal/Unseal the key. The endpoint should be specified as a URL with an explicit scheme, e.g. `https://kms.example.com:4443`. With the `https://` scheme, the connection to the KMS server is established over TLS, and the server certificate is verified against the trusted root CAs. WARNING: if the scheme is omitted (e.g. `kms.example.com:4443`) or set to `grpc://`, the connection to the KMS server is established without TLS, and the disk encryption key material is transmitted in plaintext. Use plaintext endpoints only on fully trusted networks. Note: when encrypting the `STATE` volume, custom trusted root CAs from the machine configuration might not be available when unlocking the volume (as the machine configuration is stored on `STATE`), so the KMS server certificate should be signed by a CA trusted by default.

tpm

EncryptionKeyTPM represents a key that is generated and then sealed/unsealed by the TPM.

Field	Type	Description	Value(s)
`options`	EncryptionKeyTPMOptions	TPM options for key protection.
`checkSecurebootStatusOnEnroll`	bool	Check that Secureboot is enabled in the EFI firmware. If Secureboot is not enabled, the enrollment of the key will fail.

options

EncryptionKeyTPMOptions represents the options for TPM-based key protection.

Field	Type	Description	Value(s)
`pcrs`	[]int	List of PCRs to bind the key to. If not set, defaults to PCR 7, can be disabled by passing an empty list.

mount

UserMountSpec describes how the volume is mounted.

Field	Type	Description	Value(s)
`disableAccessTime`	bool	If true, disable file access time updates.
`secure`	bool	Enable secure mount options (nosuid, nodev, noexec). Defaults to true for better security.

trim

TrimConfig describes per-volume filesystem trim (fstrim) configuration. It overrides the global FilesystemTrimConfig for the volume.

Field	Type	Description
`enabled`	bool	Enable or disable trimming for this volume. If not set, trimming is enabled when the global FilesystemTrimConfig is present.
`interval`	Duration	The interval at which the volume is trimmed, overriding the global trim interval.
`chunkSize`	ByteSize	The size of the filesystem range trimmed at once, overriding the global chunk size. Setting it explicitly to zero trims the whole filesystem at once. When set to a non-zero value, the chunk size must be at least 1MiB. Size is specified in bytes, but can be expressed in human readable format, e.g. 1GiB.
`chunkDelay`	Duration	The delay between trimming consecutive chunks, overriding the global chunk delay. Setting it explicitly to zero trims the chunks back-to-back.
`minLength`	ByteSize	The minimum contiguous free range to discard, overriding the global minimum length. The value cannot exceed 128MiB, as ext4 rejects values larger than the block group size. Size is specified in bytes, but can be expressed in human readable format, e.g. 1MiB.

scrub

ScrubConfig describes per-volume filesystem scrub configuration. It overrides the global FilesystemScrubConfig for the volume.

Field	Type	Description	Value(s)
`enabled`	bool	Enable or disable scrubbing for this volume. If not set, scrubbing is enabled by default when scrub section is present.
`interval`	Duration	The interval at which the volume is scrubbed, overriding the global scrub interval.

Overview

Getting Started

Platform specific installation

Deploying and managing workloads

Networking

Security

Build and extend Talos

Configure your Talos cluster

Advanced guides

Reference

Troubleshooting and support

Learn more

provisioning

diskSelector

filesystem

xfs

encryption

keys[]

static

nodeID

kms

tpm

options

mount

trim

scrub

​provisioning

​diskSelector

​filesystem

​xfs

​encryption

​keys[]

​static

​nodeID

​kms

​tpm

options

​mount

​trim

​scrub

provisioning

diskSelector

filesystem

xfs

encryption

keys[]

static

nodeID

kms

tpm

mount

trim

scrub