Skip to main content
version: v1alpha1
machine: # ...
cluster: # ...
FieldTypeDescriptionValue(s)
versionstringIndicates the schema used to decode the contents.v1alpha1
debugboolEnable verbose logging to the console.
All system containers logs will flow into serial console.

Note: To avoid breaking Talos bootstrap flow enable this option only if serial console can handle high message throughput.
true
yes
false
no
machineMachineConfigProvides machine specific configuration options.
clusterClusterConfigProvides cluster specific configuration options.

machine

MachineConfig represents the machine-specific config values.
machine:
    type: controlplane
    # InstallConfig represents the installation options for preparing a node.
    install:
        disk: /dev/sda # The disk used for installations.
        image: factory.talos.dev/metal-installer/376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba:latest # Allows for supplying the image used to perform the installation.
        wipe: false # Indicates if the installation disk should be wiped at installation time.
        grubUseUKICmdline: true # Indicates if legacy GRUB bootloader should use kernel cmdline from the UKI instead of building it on the host.

        # # Look up disk using disk attributes like model, size, serial and others.
        # diskSelector:
        #     size: 4GB # Disk size.
        #     model: WDC* # Disk model `/sys/block/<dev>/device/model`.
        #     busPath: /pci0000:00/0000:00:17.0/ata1/host0/target0:0:0/0:0:0:0 # Disk bus path.
FieldTypeDescriptionValue(s)
typestringDefines the role of the machine within the cluster.

Control Plane

Control Plane node type designates the node as a control plane member.
This means it will host etcd along with the Kubernetes controlplane components such as API Server, Controller Manager, Scheduler.

Worker

Worker node type designates the node as a worker node.
This means it will be an available compute node for scheduling workloads.

This node type was previously known as “join”; that value is still supported but deprecated.
controlplane
worker
tokenstringThe token is used by a machine to join the PKI of the cluster.
Using this token, a machine will create a certificate signing request (CSR), and request a certificate that will be used as its’ identity.
caPEMEncodedCertificateAndKeyThe root certificate authority of the PKI.
It is composed of a base64 encoded crt and key.
acceptedCAs[]PEMEncodedCertificateThe certificates issued by certificate authorities are accepted in addition to issuing ‘ca’.
It is composed of a base64 encoded `crt“.
certSANs[]stringExtra certificate subject alternative names for the machine’s certificate.
By default, all non-loopback interface IPs are automatically added to the certificate’s SANs.
kubeletKubeletConfigUsed to provide additional options to the kubelet.
pods[]UnstructuredUsed to provide static pod definitions to be run by the kubelet directly bypassing the kube-apiserver.

Static pods can be used to run components which should be started before the Kubernetes control plane is up.
Talos doesn’t validate the pod definition.
Updates to this field can be applied without a reboot.

See https://kubernetes.io/docs/tasks/configure-pod-container/static-pod/.
installInstallConfigUsed to provide instructions for installations.

Note that this configuration section gets silently ignored by Talos images that are considered pre-installed.
To make sure Talos installs according to the provided configuration, Talos should be booted with ISO or PXE-booted.
filesMachineFileAllows the addition of user specified files.
The value of op can be create, overwrite, or append.
In the case of create, path must not exist.
In the case of overwrite, and append, path must be a valid file.
If an op value of append is used, the existing file will be appended.
Note that the file contents are not required to be base64 encoded.
featuresFeaturesConfigFeatures describe individual Talos features that can be switched on or off.
udevUdevConfigConfigures the udev system.
loggingLoggingConfigConfigures the logging system.
kernelKernelConfigConfigures the kernel.
seccompProfilesMachineSeccompProfileConfigures the seccomp profiles for the machine.
baseRuntimeSpecOverridesUnstructuredOverride (patch) settings in the default OCI runtime spec for CRI containers.

It can be used to set some default container settings which are not configurable in Kubernetes,
for example default ulimits.
Note: this change applies to all newly created containers, and it requires a reboot to take effect.
nodeLabelsmap[string]stringConfigures the node labels for the machine.

Note: In the default Kubernetes configuration, worker nodes are restricted to set
labels with some prefixes (see NodeRestriction admission plugin).
nodeAnnotationsmap[string]stringConfigures the node annotations for the machine.
nodeTaintsmap[string]stringConfigures the node taints for the machine. Effect is optional.

Note: In the default Kubernetes configuration, worker nodes are not allowed to
modify the taints (see NodeRestriction admission plugin).

kubelet

KubeletConfig represents the kubelet config values.
machine:
    kubelet:
        image: ghcr.io/siderolabs/kubelet:v1.36.2 # The `image` field is an optional reference to an alternative kubelet image.
        # The `extraArgs` field is used to provide additional flags to the kubelet.
        extraArgs:
            feature-gates: ServerSideApply=true

        # # The `ClusterDNS` field is an optional reference to an alternative kubelet clusterDNS ip list.
        # clusterDNS:
        #     - 10.96.0.10
        #     - 169.254.2.53

        # # The `extraMounts` field is used to add additional mounts to the kubelet container.
        # extraMounts:
        #     - destination: /var/lib/example # Destination is the absolute path where the mount will be placed in the container.
        #       type: bind # Type specifies the mount kind.
        #       source: /var/lib/example # Source specifies the source path of the mount.
        #       # Options are fstab style mount options.
        #       options:
        #         - bind
        #         - rshared
        #         - rw

        # # The `extraConfig` field is used to provide kubelet configuration overrides.
        # extraConfig:
        #     serverTLSBootstrap: true

        # # The `KubeletCredentialProviderConfig` field is used to provide kubelet credential configuration.
        # credentialProviderConfig:
        #     apiVersion: kubelet.config.k8s.io/v1
        #     kind: CredentialProviderConfig
        #     providers:
        #         - apiVersion: credentialprovider.kubelet.k8s.io/v1
        #           defaultCacheDuration: 12h
        #           matchImages:
        #             - '*.dkr.ecr.*.amazonaws.com'
        #             - '*.dkr.ecr.*.amazonaws.com.cn'
        #             - '*.dkr.ecr-fips.*.amazonaws.com'
        #             - '*.dkr.ecr.us-iso-east-1.c2s.ic.gov'
        #             - '*.dkr.ecr.us-isob-east-1.sc2s.sgov.gov'
        #           name: ecr-credential-provider

        # # The `nodeIP` field is used to configure `--node-ip` flag for the kubelet.
        # nodeIP:
        #     # The `validSubnets` field configures the networks to pick kubelet node IP from.
        #     validSubnets:
        #         - 10.0.0.0/8
        #         - '!10.0.0.3/32'
        #         - fdc7::/16
FieldTypeDescriptionValue(s)
imagestringThe image field is an optional reference to an alternative kubelet image.
clusterDNS[]stringThe ClusterDNS field is an optional reference to an alternative kubelet clusterDNS ip list.
extraArgsArgsThe extraArgs field is used to provide additional flags to the kubelet.
extraMountsExtraMountThe extraMounts field is used to add additional mounts to the kubelet container.
Note that either bind or rbind are required in the options.
extraConfigUnstructuredThe extraConfig field is used to provide kubelet configuration overrides.

Some fields are not allowed to be overridden: authentication and authorization, cgroups
configuration, ports, etc.
credentialProviderConfigUnstructuredThe KubeletCredentialProviderConfig field is used to provide kubelet credential configuration.
defaultRuntimeSeccompProfileEnabledboolEnable container runtime default Seccomp profile.true
yes
false
no
registerWithFQDNboolThe registerWithFQDN field is used to force kubelet to use the node FQDN for registration.
This is required in clouds like AWS.
true
yes
false
no
nodeIPKubeletNodeIPConfigThe nodeIP field is used to configure --node-ip flag for the kubelet.
This is used when a node has multiple addresses to choose from.
skipNodeRegistrationboolThe skipNodeRegistration is used to run the kubelet without registering with the apiserver.
This runs kubelet as standalone and only runs static pods.
true
yes
false
no
disableManifestsDirectoryboolThe disableManifestsDirectory field configures the kubelet to get static pod manifests from the /etc/kubernetes/manifests directory.
It’s recommended to configure static pods with the “pods” key instead.
true
yes
false
no

extraMounts[]

ExtraMount wraps OCI Mount specification.
machine:
    kubelet:
        extraMounts:
            - destination: /var/lib/example # Destination is the absolute path where the mount will be placed in the container.
              type: bind # Type specifies the mount kind.
              source: /var/lib/example # Source specifies the source path of the mount.
              # Options are fstab style mount options.
              options:
                - bind
                - rshared
                - rw
FieldTypeDescriptionValue(s)
destinationstringDestination is the absolute path where the mount will be placed in the container.
typestringType specifies the mount kind.
sourcestringSource specifies the source path of the mount.
options[]stringOptions are fstab style mount options.
uidMappingsLinuxIDMappingUID/GID mappings used for changing file owners w/o calling chown, fs should support it.

Every mount point could have its own mapping.
gidMappingsLinuxIDMappingUID/GID mappings used for changing file owners w/o calling chown, fs should support it.

Every mount point could have its own mapping.
uidMappings[]
LinuxIDMapping represents the Linux ID mapping.
FieldTypeDescriptionValue(s)
containerIDuint32ContainerID is the starting UID/GID in the container.
hostIDuint32HostID is the starting UID/GID on the host to be mapped to ‘ContainerID’.
sizeuint32Size is the number of IDs to be mapped.
gidMappings[]
LinuxIDMapping represents the Linux ID mapping.
FieldTypeDescriptionValue(s)
containerIDuint32ContainerID is the starting UID/GID in the container.
hostIDuint32HostID is the starting UID/GID on the host to be mapped to ‘ContainerID’.
sizeuint32Size is the number of IDs to be mapped.

nodeIP

KubeletNodeIPConfig represents the kubelet node IP configuration.
machine:
    kubelet:
        nodeIP:
            # The `validSubnets` field configures the networks to pick kubelet node IP from.
            validSubnets:
                - 10.0.0.0/8
                - '!10.0.0.3/32'
                - fdc7::/16
FieldTypeDescriptionValue(s)
validSubnets[]stringThe validSubnets field configures the networks to pick kubelet node IP from.
For dual stack configuration, there should be two subnets: one for IPv4, another for IPv6.
IPs can be excluded from the list by using negative match with !, e.g !10.0.0.0/8.
Negative subnet matches should be specified last to filter out IPs picked by positive matches.
If not specified, node IP is picked based on cluster podCIDRs: IPv4/IPv6 address or both.

install

InstallConfig represents the installation options for preparing a node.
machine:
    install:
        disk: /dev/sda # The disk used for installations.
        image: factory.talos.dev/metal-installer/376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba:latest # Allows for supplying the image used to perform the installation.
        wipe: false # Indicates if the installation disk should be wiped at installation time.
        grubUseUKICmdline: true # Indicates if legacy GRUB bootloader should use kernel cmdline from the UKI instead of building it on the host.

        # # Look up disk using disk attributes like model, size, serial and others.
        # diskSelector:
        #     size: 4GB # Disk size.
        #     model: WDC* # Disk model `/sys/block/<dev>/device/model`.
        #     busPath: /pci0000:00/0000:00:17.0/ata1/host0/target0:0:0/0:0:0:0 # Disk bus path.
FieldTypeDescriptionValue(s)
diskstringThe disk used for installations.
diskSelectorInstallDiskSelectorLook up disk using disk attributes like model, size, serial and others.
Always has priority over disk.
imagestringAllows for supplying the image used to perform the installation.
Image reference for each Talos release can be found on
GitHub releases page.
wipeboolIndicates if the installation disk should be wiped at installation time.
Defaults to true.
true
yes
false
no
legacyBIOSSupportboolIndicates if MBR partition should be marked as bootable (active).
Should be enabled only for the systems with legacy BIOS that doesn’t support GPT partitioning scheme.
grubUseUKICmdlineboolIndicates if legacy GRUB bootloader should use kernel cmdline from the UKI instead of building it on the host.
This changes the way cmdline is managed with GRUB bootloader to be more consistent with UKI/systemd-boot.

diskSelector

InstallDiskSelector represents a disk query parameters for the install disk lookup.
machine:
    install:
        diskSelector:
            size: '>= 1TB' # Disk size.
            model: WDC* # Disk model `/sys/block/<dev>/device/model`.

            # # Disk bus path.
            # busPath: /pci0000:00/0000:00:17.0/ata1/host0/target0:0:0/0:0:0:0
            # busPath: /pci0000:00/*
FieldTypeDescriptionValue(s)
sizeInstallDiskSizeMatcherDisk size.
namestringDisk name /sys/block/<dev>/device/name.
modelstringDisk model /sys/block/<dev>/device/model.
serialstringDisk serial number /sys/block/<dev>/serial.
modaliasstringDisk modalias /sys/block/<dev>/device/modalias.
uuidstringDisk UUID /sys/block/<dev>/uuid.
wwidstringDisk WWID /sys/block/<dev>/wwid.
typeInstallDiskTypeDisk Type.ssd
hdd
nvme
sd
busPathstringDisk bus path.

files[]

MachineFile represents a file to write to disk.
machine:
    files:
        - content: '...' # The contents of the file.
          permissions: 0o666 # The file's permissions in octal.
          path: /tmp/file.txt # The path of the file.
          op: append # The operation to use
FieldTypeDescriptionValue(s)
contentstringThe contents of the file.
permissionsFileModeThe file’s permissions in octal.
pathstringThe path of the file.
opstringThe operation to usecreate
append
overwrite

features

FeaturesConfig describes individual Talos features that can be switched on or off.
machine:
    features:
        diskQuotaSupport: true # Enable XFS project quota support for EPHEMERAL partition and user disks.

        # # Configure Talos API access from Kubernetes pods.
        # kubernetesTalosAPIAccess:
        #     enabled: true # Enable Talos API access from Kubernetes pods.
        #     # The list of Talos API roles which can be granted for access from Kubernetes pods.
        #     allowedRoles:
        #         - os:reader
        #     # The list of Kubernetes namespaces Talos API access is available from.
        #     allowedKubernetesNamespaces:
        #         - kube-system
FieldTypeDescriptionValue(s)
kubernetesTalosAPIAccessKubernetesTalosAPIAccessConfigConfigure Talos API access from Kubernetes pods.

This feature is disabled if the feature config is not specified.
diskQuotaSupportboolEnable XFS project quota support for EPHEMERAL partition and user disks.
Also enables kubelet tracking of ephemeral disk usage in the kubelet via quota.
kubePrismKubePrismKubePrism - local proxy/load balancer on defined port that will distribute
requests to all API servers in the cluster.
nodeAddressSortAlgorithmstringSelect the node address sort algorithm.
The ‘v1’ algorithm sorts addresses by the address itself.
The ‘v2’ algorithm prefers more specific prefixes.
If unset, defaults to ‘v1’.

kubernetesTalosAPIAccess

KubernetesTalosAPIAccessConfig describes the configuration for the Talos API access from Kubernetes pods.
machine:
    features:
        kubernetesTalosAPIAccess:
            enabled: true # Enable Talos API access from Kubernetes pods.
            # The list of Talos API roles which can be granted for access from Kubernetes pods.
            allowedRoles:
                - os:reader
            # The list of Kubernetes namespaces Talos API access is available from.
            allowedKubernetesNamespaces:
                - kube-system
FieldTypeDescriptionValue(s)
enabledboolEnable Talos API access from Kubernetes pods.
allowedRoles[]stringThe list of Talos API roles which can be granted for access from Kubernetes pods.

Empty list means that no roles can be granted, so access is blocked.
allowedKubernetesNamespaces[]stringThe list of Kubernetes namespaces Talos API access is available from.

kubePrism

KubePrism describes the configuration for the KubePrism load balancer.
FieldTypeDescriptionValue(s)
enabledboolEnable KubePrism support - will start local load balancing proxy.
portintKubePrism port.

udev

UdevConfig describes how the udev system should be configured.
machine:
    udev:
        # List of udev rules to apply to the udev system
        rules:
            - SUBSYSTEM=="drm", KERNEL=="renderD*", GROUP="44", MODE="0660"
FieldTypeDescriptionValue(s)
rules[]stringList of udev rules to apply to the udev system

logging

LoggingConfig struct configures Talos logging.
machine:
    logging:
        # Logging destination.
        destinations:
            - endpoint: tcp://1.2.3.4:12345 # Where to send logs. Supported protocols are "tcp" and "udp".
              format: json_lines # Logs format.
machine:
    logging:
        # Logging destination.
        destinations:
            - endpoint: udp://127.0.0.1:12345 # Where to send logs. Supported protocols are "tcp" and "udp".
              format: json_lines # Logs format.
              # Extra tags (key-value) pairs to attach to every log message sent.
              extraTags:
                machine: worker-1
FieldTypeDescriptionValue(s)
destinationsLoggingDestinationLogging destination.

destinations[]

LoggingDestination struct configures Talos logging destination.
FieldTypeDescriptionValue(s)
endpointEndpointWhere to send logs. Supported protocols are “tcp” and “udp”.
formatstringLogs format.json_lines
extraTagsmap[string]stringExtra tags (key-value) pairs to attach to every log message sent.
endpoint
Endpoint represents the endpoint URL parsed out of the machine config.
FieldTypeDescriptionValue(s)

kernel

KernelConfig struct configures Talos Linux kernel.
machine:
    kernel:
        # Kernel modules to load.
        modules:
            - name: btrfs # Module name.
FieldTypeDescriptionValue(s)
modulesKernelModuleConfigKernel modules to load.

modules[]

KernelModuleConfig struct configures Linux kernel modules to load.
FieldTypeDescriptionValue(s)
namestringModule name.
parameters[]stringModule parameters, changes applied after reboot.

seccompProfiles[]

MachineSeccompProfile defines seccomp profiles for the machine.
machine:
    seccompProfiles:
        - name: audit.json # The `name` field is used to provide the file name of the seccomp profile.
          # The `value` field is used to provide the seccomp profile.
          value:
            defaultAction: SCMP_ACT_LOG
FieldTypeDescriptionValue(s)
namestringThe name field is used to provide the file name of the seccomp profile.
valueUnstructuredThe value field is used to provide the seccomp profile.

cluster

ClusterConfig represents the cluster-wide config values.
cluster:
    # ControlPlaneConfig represents the control plane configuration options.
    controlPlane:
        endpoint: https://1.2.3.4 # Endpoint is the canonical controlplane endpoint, which can be an IP address or a DNS hostname.
    clusterName: talos.local
FieldTypeDescriptionValue(s)
idstringGlobally unique identifier for this cluster (base64 encoded random 32 bytes).
secretstringShared secret of cluster (base64 encoded random 32 bytes).
This secret is shared among cluster members but should never be sent over the network.
controlPlaneControlPlaneConfigProvides control plane specific configuration options.
clusterNamestringConfigures the cluster’s name.
tokenstringThe bootstrap token used to join the cluster.
caPEMEncodedCertificateAndKeyThe base64 encoded root certificate authority used by Kubernetes.
acceptedCAs[]PEMEncodedCertificateThe list of base64 encoded accepted certificate authorities used by Kubernetes.
aggregatorCAPEMEncodedCertificateAndKeyThe base64 encoded aggregator certificate authority used by Kubernetes for front-proxy certificate generation.

This CA can be self-signed.
serviceAccountPEMEncodedKeyThe base64 encoded private key for service account token generation.
etcdEtcdConfigEtcd specific configuration options.
coreDNSCoreDNSCore DNS specific configuration options.
externalCloudProviderExternalCloudProviderConfigExternal cloud provider configuration.
extraManifests[]stringA list of urls that point to additional manifests.
These will get automatically deployed as part of the bootstrap.
extraManifestHeadersmap[string]stringA map of key value pairs that will be added while fetching the extraManifests.
inlineManifestsClusterInlineManifestA list of inline Kubernetes manifests.
These will get automatically deployed as part of the bootstrap.
adminKubeconfigAdminKubeconfigConfigSettings for admin kubeconfig generation.
Certificate lifetime can be configured.
allowSchedulingOnControlPlanesboolAllows running workload on control-plane nodes.true
yes
false
no

controlPlane

ControlPlaneConfig represents the control plane configuration options.
cluster:
    controlPlane:
        endpoint: https://1.2.3.4 # Endpoint is the canonical controlplane endpoint, which can be an IP address or a DNS hostname.
FieldTypeDescriptionValue(s)
endpointEndpointEndpoint is the canonical controlplane endpoint, which can be an IP address or a DNS hostname.
It is single-valued, and may optionally include a port number.

endpoint

Endpoint represents the endpoint URL parsed out of the machine config.
FieldTypeDescriptionValue(s)

etcd

EtcdConfig represents the etcd configuration options.
cluster:
    etcd:
        image: registry.k8s.io/etcd:3.7.0-rc.0-0 # The container image used to create the etcd service.
        # The `ca` is the root certificate authority of the PKI.
        ca:
            crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t
            key: LS0tIEVYQU1QTEUgS0VZIC0tLQ==
        # Extra arguments to supply to etcd.
        extraArgs:
            election-timeout: "5000"

        # # The `advertisedSubnets` field configures the networks to pick etcd advertised IP from.
        # advertisedSubnets:
        #     - 10.0.0.0/8
FieldTypeDescriptionValue(s)
imagestringThe container image used to create the etcd service.
caPEMEncodedCertificateAndKeyThe ca is the root certificate authority of the PKI.
It is composed of a base64 encoded crt and key.
extraArgsArgsExtra arguments to supply to etcd.
Note that the following args are not allowed:

- name
- data-dir
- initial-cluster-state
- listen-peer-urls
- listen-client-urls
- cert-file
- key-file
- trusted-ca-file
- peer-client-cert-auth
- peer-cert-file
- peer-trusted-ca-file
- peer-key-file
advertisedSubnets[]stringThe advertisedSubnets field configures the networks to pick etcd advertised IP from.

IPs can be excluded from the list by using negative match with !, e.g !10.0.0.0/8.
Negative subnet matches should be specified last to filter out IPs picked by positive matches.
If not specified, advertised IP is selected as the first routable address of the node.
listenSubnets[]stringThe listenSubnets field configures the networks for the etcd to listen for peer and client connections.

If listenSubnets is not set, but advertisedSubnets is set, listenSubnets defaults to
advertisedSubnets.

If neither advertisedSubnets nor listenSubnets is set, listenSubnets defaults to listen on all addresses.

IPs can be excluded from the list by using negative match with !, e.g !10.0.0.0/8.
Negative subnet matches should be specified last to filter out IPs picked by positive matches.
If not specified, advertised IP is selected as the first routable address of the node.

coreDNS

CoreDNS represents the CoreDNS config values.
cluster:
    coreDNS:
        image: registry.k8s.io/coredns/coredns:v1.14.2 # The `image` field is an override to the default coredns image.
FieldTypeDescriptionValue(s)
disabledboolDisable coredns deployment on cluster bootstrap.
imagestringThe image field is an override to the default coredns image.

externalCloudProvider

ExternalCloudProviderConfig contains external cloud provider configuration.
cluster:
    externalCloudProvider:
        enabled: true # Enable external cloud provider.
        # A list of urls that point to additional manifests for an external cloud provider.
        manifests:
            - https://raw.githubusercontent.com/kubernetes/cloud-provider-aws/v1.20.0-alpha.0/manifests/rbac.yaml
            - https://raw.githubusercontent.com/kubernetes/cloud-provider-aws/v1.20.0-alpha.0/manifests/aws-cloud-controller-manager-daemonset.yaml
FieldTypeDescriptionValue(s)
enabledboolEnable external cloud provider.true
yes
false
no
manifests[]stringA list of urls that point to additional manifests for an external cloud provider.
These will get automatically deployed as part of the bootstrap.

inlineManifests[]

ClusterInlineManifest struct describes inline bootstrap manifests for the user.
cluster:
    inlineManifests:
        - name: namespace-ci # Name of the manifest.
          contents: |- # Manifest contents as a string.
            apiVersion: v1
            kind: Namespace
            metadata:
            	name: ci
FieldTypeDescriptionValue(s)
namestringName of the manifest.
Name should be unique.
contentsstringManifest contents as a string.

adminKubeconfig

AdminKubeconfigConfig contains admin kubeconfig settings.
cluster:
    adminKubeconfig:
        certLifetime: 1h0m0s # Admin kubeconfig certificate lifetime (default is 1 year).
FieldTypeDescriptionValue(s)
certLifetimeDurationAdmin kubeconfig certificate lifetime (default is 1 year).
Field format accepts any Go time.Duration format (‘1h’ for one hour, ‘10m’ for ten minutes).