Skip to main content
The Talos Linux Configuration API defines the structure and types used to configure Talos machines and clusters. Configuration is expressed through versioned, structured documents that describe machine behavior, cluster settings, and system resources.

​
Schema Versioning

Talos configuration uses a versioned schema approach to maintain backward compatibility while allowing the system to evolve.

​
Current Version: v1alpha1

The primary configuration version is v1alpha1, which contains most configuration options. All configuration documents must specify their version: 
version: v1alpha1
kind: Config

​
Multi-Document Configuration

Modern Talos configurations support multiple documents in a single file. This allows separation of concerns:
  • v1alpha1.Config - Main machine and cluster configuration
  • Network Documents - HostnameConfig, NetworkDeviceConfig, ResolverConfig
  • Block Storage Documents - UserVolumeConfig, VolumeConfig, ExistingVolumeConfig
  • Runtime Documents - Various runtime configuration types
Multiple documents are separated by --- in YAML format.

​
Configuration Structure

The root Config document contains two primary sections:

MachineConfig

Machine-specific settings including networking, installation, and kubelet configuration

ClusterConfig

Cluster-wide settings including control plane, networking, and Kubernetes components

​
Configuration Generation

Talos provides tools to generate valid configurations: 
# Generate a new configuration
talosctl gen config my-cluster https://controlplane.example.com:6443

# Generate with custom options
talosctl gen config my-cluster https://controlplane.example.com:6443 \
  --kubernetes-version 1.28.0 \
  --install-disk /dev/sda

​
Configuration Validation

All configuration types implement validation to ensure correctness:
  • Required fields - Certain fields must be present
  • Type validation - Values must match expected types and constraints
  • Cross-field validation - Some fields have dependencies or conflicts
  • Runtime validation - Some checks are mode-specific (container, cloud, metal)

​
Configuration Application

Configurations can be applied in multiple ways:

​
During Installation

Configuration is provided during initial installation: 
talosctl apply-config --insecure --nodes 192.168.1.10 --file controlplane.yaml

​
Runtime Updates

Many configuration changes can be applied at runtime without reboots: 
talosctl apply-config --nodes controlplane-1 --file updated-config.yaml

​
Configuration Patches

Partial updates using JSON patches: 
talosctl patch machineconfig --nodes controlplane-1 --patch @patch.yaml

​
Configuration Best Practices

Use device selectors instead of hard-coded interface names for better portability across hardware.
Never commit raw secrets to version control. Use secret management tools or generate fresh secrets per environment.
Always validate configurations before applying to production systems.
Prefer the newer multi-document format for better modularity and to avoid deprecated fields.

​
Document Types Reference

​
Core Configuration

  • Config (v1alpha1) - Root configuration document containing machine and cluster config

​
Network Configuration

  • HostnameConfig - Static or auto-generated hostname configuration
  • NetworkDeviceConfig - Network interface configuration
  • ResolverConfig - DNS resolver configuration
  • StaticHostConfig - Static /etc/hosts entries
  • KubeSpanConfig - KubeSpan overlay network configuration

​
Storage Configuration

  • UserVolumeConfig - User-managed volumes and partitions
  • VolumeConfig - System volume configuration
  • ExistingVolumeConfig - Mount existing volumes
  • RawVolumeConfig - Raw volume mounting
  • SwapVolumeConfig - Swap space configuration

​
Runtime Configuration

  • EnvironmentConfig - Environment variables
  • TimeSyncConfig - Time synchronization
  • ExtensionServiceConfig - System extensions
  • KmsgLogConfig - Kernel message logging

​
Next Steps

Machine Configuration

Explore machine-specific configuration options

Cluster Configuration

Learn about cluster-wide settings

Network Configuration

Configure networking for your machines

Block Storage

Set up disks and volumes

Build docs developers (and LLMs) love

Get started for freeTalk to us