Skip to main content
Machine configuration defines node-specific settings including the machine type, installation parameters, kubelet configuration, and node-level customizations.

​
Machine Type

Every node must specify its role in the cluster:
​
machine.type
string
required
The role of the machine within the cluster.Control Plane: Hosts etcd and Kubernetes control plane components (API server, controller manager, scheduler).Worker: Compute node for scheduling workloads.
machine:
  type: controlplane  # or worker

​
Machine Token and CA

Machines join the cluster PKI using a token and certificate authority:
​
machine.token
string
required
Token used by a machine to join the cluster PKI. The machine creates a certificate signing request (CSR) using this token to obtain its identity certificate.
Ensure this token is correct as machine certificates have a short TTL by default.
​
machine.ca
object
The root certificate authority of the PKI. Base64 encoded certificate and key.
machine:
  token: "328hom.uqjzh6jnn2eie9oi"
  ca:
    crt: LS0tLS1CRUdJTi...
    key: LS0tLS1CRUdJTi...

​
Certificate SANs

​
machine.certSANs
array
Extra certificate subject alternative names for the machine’s certificate. By default, all non-loopback interface IPs are automatically added to the certificate’s SANs.
machine:
  certSANs:
    - 10.0.0.10
    - 172.16.0.10  
    - node1.example.com

​
Control Plane Configuration

Control plane nodes can have additional configuration:
​
machine.controlPlane
object
Machine-specific control plane configuration options.
machine:
  controlPlane:
    controllerManager:
      disabled: false
    scheduler:
      disabled: false

​
Disabling Components

​
machine.controlPlane.controllerManager.disabled
boolean
default:"false"
Disable kube-controller-manager on this specific control plane node.
​
machine.controlPlane.scheduler.disabled
boolean
default:"false"
Disable kube-scheduler on this specific control plane node.

​
Kubelet Configuration

Configure the kubelet running on the machine:
​
machine.kubelet
object
Kubelet configuration options.
machine:
  kubelet:
    image: ghcr.io/siderolabs/kubelet:v1.30.0
    clusterDNS:
      - 10.96.0.10
      - 169.254.2.53
    extraArgs:
      rotate-server-certificates: "true"
      feature-gates: "ServerSideApply=true"
    registerWithFQDN: true

​
Kubelet Options

​
machine.kubelet.image
string
Optional reference to an alternative kubelet image.
​
machine.kubelet.clusterDNS
array
Alternative kubelet clusterDNS IP list. Overrides the default DNS service IPs.
​
machine.kubelet.extraArgs
object
Additional flags to pass to the kubelet. Values can be strings or arrays of strings.
​
machine.kubelet.extraMounts
array
Additional mounts for the kubelet container. Either bind or rbind are required in the options.
​
machine.kubelet.extraConfig
object
Kubelet configuration overrides. Some fields like authentication, authorization, cgroups configuration, and ports cannot be overridden.
​
machine.kubelet.registerWithFQDN
boolean
default:"false"
Force kubelet to use the node FQDN for registration. Required in clouds like AWS.
​
machine.kubelet.nodeIP.validSubnets
array
Networks to pick kubelet node IP from. For dual stack, specify one IPv4 and one IPv6 subnet. Use ! prefix for negative matches.
machine:
  kubelet:
    nodeIP:
      validSubnets:
        - 10.0.0.0/8
        - "!10.0.0.3/32"
        - fdc7::/16
​
machine.kubelet.skipNodeRegistration
boolean
default:"false"
Run kubelet without registering with the API server. Runs kubelet standalone and only runs static pods.

​
Installation Configuration

Define how Talos is installed on the machine:
​
machine.install
object
Installation options for preparing the node.
This configuration section is silently ignored by pre-installed Talos images. To ensure installation according to config, boot with ISO or PXE.
machine:
  install:
    disk: /dev/sda
    image: ghcr.io/siderolabs/installer:v1.8.0
    wipe: true

​
Installation Options

​
machine.install.disk
string
The disk used for installation (e.g., /dev/sda, /dev/nvme0).
​
machine.install.diskSelector
object
Look up disk using attributes like model, size, serial. Always has priority over disk.
machine:
  install:
    diskSelector:
      size: ">= 100GB"
      model: "WDC*"
      type: nvme
​
machine.install.image
string
The installer image to use. Find image references for each release on GitHub releases.
​
machine.install.wipe
boolean
default:"true"
Indicates if the installation disk should be wiped at installation time.
​
machine.install.legacyBIOSSupport
boolean
default:"false"
Mark MBR partition as bootable (active). Enable only for systems with legacy BIOS that don’t support GPT partitioning.

​
Files

Add custom files to the machine:
​
machine.files
array
User-specified files to create on the machine.
machine:
  files:
    - content: |
        [Unit]
        Description=Custom service
        [Service]
        Type=oneshot
        ExecStart=/bin/echo Hello
      permissions: 0o644
      path: /var/etc/custom.service
      op: create

​
File Options

​
machine.files[].content
string
required
The file contents. Not required to be base64 encoded.
​
machine.files[].permissions
number
required
The file permissions in octal format.
​
machine.files[].path
string
required
The file path relative to /var.
​
machine.files[].op
string
required
The operation to perform:
  • create - Path must not exist
  • overwrite - Path must be a valid file
  • append - Append to existing file

​
System Configuration

​
Sysctls

​
machine.sysctls
object
Kernel sysctl parameters.
machine:
  sysctls:
    kernel.domainname: talos.dev
    net.ipv4.ip_forward: "1"
    net/ipv6/conf/eth0.100/disable_ipv6: "1"

​
Sysfs

​
machine.sysfs
object
Sysfs parameters.
machine:
  sysfs:
    devices.system.cpu.cpu0.cpufreq.scaling_governor: performance

​
Node Labels and Taints

​
machine.nodeLabels
object
Kubernetes node labels for the machine.
Worker nodes are restricted to set labels with certain prefixes by the NodeRestriction admission plugin.
​
machine.nodeAnnotations
object
Kubernetes node annotations for the machine.
​
machine.nodeTaints
object
Kubernetes node taints for the machine. Effect is optional.
Worker nodes are not allowed to modify taints by the NodeRestriction admission plugin.
machine:
  nodeLabels:
    rack: r13a25
    environment: production
  nodeAnnotations:
    customer.io/rack: r13a25
  nodeTaints:
    special: "true:NoSchedule"

​
Features

​
machine.features
object
Individual Talos features that can be enabled or disabled.
machine:
  features:
    rbac: true
    stableHostname: true
    kubernetesTalosAPIAccess:
      enabled: true
      allowedRoles:
        - os:reader
      allowedKubernetesNamespaces:
        - kube-system

​
Logging

​
machine.logging
object
Configure the logging system.
machine:
  logging:
    destinations:
      - endpoint: tcp://192.168.1.50:5140
        format: json_lines

​
Kernel Configuration

​
machine.kernel
object
Kernel configuration including modules to load.
machine:
  kernel:
    modules:
      - name: btrfs
      - name: br_netfilter

​
Example: Control Plane

version: v1alpha1
machine:
  type: controlplane
  token: abc123.def456ghi789jkl
  ca:
    crt: LS0tLS...
    key: LS0tLS...
  certSANs:
    - 192.168.1.100
    - cp.example.com
  kubelet:
    extraArgs:
      rotate-server-certificates: "true"
    nodeIP:
      validSubnets:
        - 192.168.1.0/24
  install:
    disk: /dev/sda
    image: ghcr.io/siderolabs/installer:v1.8.0
    wipe: true
  nodeLabels:
    node-role.kubernetes.io/control-plane: ""

​
Example: Worker

version: v1alpha1
machine:
  type: worker
  token: abc123.def456ghi789jkl
  ca:
    crt: LS0tLS...
  certSANs:
    - 192.168.1.101
  kubelet:
    extraArgs:
      max-pods: "250"
  install:
    disk: /dev/nvme0n1
    image: ghcr.io/siderolabs/installer:v1.8.0
  nodeLabels:
    workload-type: general
  nodeTaints:
    dedicated: workers:NoSchedule

Build docs developers (and LLMs) love

Get started for freeTalk to us