Skip to main content
Cluster configuration defines settings that are shared across all nodes in the cluster, including the control plane endpoint, cluster identity, Kubernetes component configuration, and networking.

​
Cluster Identity

​
cluster.id
string
Globally unique identifier for this cluster (base64 encoded random 32 bytes). Generated automatically by talosctl gen config.
​
cluster.secret
string
Shared secret of the cluster (base64 encoded random 32 bytes). This secret is shared among cluster members but should never be sent over the network.
​
cluster.clusterName
string
The name of the cluster.
cluster:
  id: YWJjZGVmZ2hpamtsbW5vcA==
  secret: cXJzdHV2d3h5ejEyMzQ1Ng==
  clusterName: talos.local

​
Control Plane

​
cluster.controlPlane.endpoint
string
required
The canonical control plane endpoint, which can be an IP address or DNS hostname. Must be a single-valued endpoint and may optionally include a port number.
This should be a stable, highly-available address (load balancer or VIP) that points to the control plane nodes.
​
cluster.controlPlane.localAPIServerPort
number
default:"6443"
The port that the API server listens on internally. May differ from the port in the endpoint field.
cluster:
  controlPlane:
    endpoint: https://192.168.1.100:6443
    localAPIServerPort: 6443

​
Cluster Network

Define pod and service network CIDRs:
​
cluster.network
object
Cluster-wide network configuration.
cluster:
  network:
    cni:
      name: flannel
    dnsDomain: cluster.local
    podSubnets:
      - 10.244.0.0/16
    serviceSubnets:
      - 10.96.0.0/12

​
Network Options

​
cluster.network.cni.name
string
default:"flannel"
CNI plugin to use. Options: flannel, custom, none.
​
cluster.network.cni.urls
array
URLs to CNI manifests to apply. Used when name is custom.
​
cluster.network.dnsDomain
string
default:"cluster.local"
The domain used by Kubernetes DNS.
​
cluster.network.podSubnets
array
default:"[\"10.244.0.0/16\"]"
The pod subnet CIDRs. Can include IPv4 and IPv6 for dual-stack clusters.
​
cluster.network.serviceSubnets
array
default:"[\"10.96.0.0/12\"]"
The service subnet CIDRs. Can include IPv4 and IPv6 for dual-stack clusters.

​
Custom CNI Example

cluster:
  network:
    cni:
      name: custom
      urls:
        - https://docs.projectcalico.org/manifests/calico.yaml

​
Kubernetes Components

​
API Server

​
cluster.apiServer
object
API server configuration.
cluster:
  apiServer:
    image: registry.k8s.io/kube-apiserver:v1.30.0
    extraArgs:
      feature-gates: ServerSideApply=true
      audit-log-path: /var/log/audit.log
    certSANs:
      - 192.168.1.100
      - api.example.com
    auditPolicy:
      apiVersion: audit.k8s.io/v1
      kind: Policy
      rules:
        - level: Metadata

​
API Server Options

​
cluster.apiServer.image
string
The container image used in the API server manifest.
​
cluster.apiServer.extraArgs
object
Extra arguments to supply to the API server.
​
cluster.apiServer.extraVolumes
array
Extra volumes to mount to the API server static pod.
​
cluster.apiServer.env
object
Environment variables for the API server.
​
cluster.apiServer.certSANs
array
Extra certificate subject alternative names for the API server’s certificate.
​
cluster.apiServer.resources
object
Configure API server resource requests and limits.

​
Controller Manager

​
cluster.controllerManager
object
Controller manager configuration.
cluster:
  controllerManager:
    image: registry.k8s.io/kube-controller-manager:v1.30.0
    extraArgs:
      node-cidr-mask-size: "24"
      feature-gates: RotateKubeletServerCertificate=true
​
cluster.controllerManager.image
string
The container image used in the controller manager manifest.
​
cluster.controllerManager.extraArgs
object
Extra arguments to supply to the controller manager.
​
cluster.controllerManager.resources
object
Configure controller manager resource requests and limits.

​
Scheduler

​
cluster.scheduler
object
Scheduler configuration.
cluster:
  scheduler:
    image: registry.k8s.io/kube-scheduler:v1.30.0
    extraArgs:
      feature-gates: AllBeta=true
​
cluster.scheduler.image
string
The container image used in the scheduler manifest.
​
cluster.scheduler.extraArgs
object
Extra arguments to supply to the scheduler.
​
cluster.scheduler.config
object
Custom kube-scheduler configuration object.

​
Kube-proxy

​
cluster.proxy
object
Kube-proxy configuration.
cluster:
  proxy:
    disabled: false
    image: registry.k8s.io/kube-proxy:v1.30.0
    mode: ipvs
    extraArgs:
      proxy-mode: ipvs
​
cluster.proxy.disabled
boolean
default:"false"
Disable kube-proxy deployment on cluster bootstrap.
​
cluster.proxy.image
string
The container image used in the kube-proxy manifest.
​
cluster.proxy.mode
string
default:"iptables"
Proxy mode: iptables or ipvs.
​
cluster.proxy.extraArgs
object
Extra arguments to supply to kube-proxy.

​
etcd

​
cluster.etcd
object
etcd cluster configuration.
cluster:
  etcd:
    image: gcr.io/etcd-development/etcd:v3.5.13
    extraArgs:
      election-timeout: "5000"
      heartbeat-interval: "500"
    advertisedSubnets:
      - 10.0.0.0/8

​
etcd Options

​
cluster.etcd.image
string
The container image used to create the etcd service.
​
cluster.etcd.ca
object
The root certificate authority of the PKI. Composed of base64 encoded crt and key.
​
cluster.etcd.extraArgs
object
Extra arguments to supply to etcd.
The following arguments are not allowed: name, data-dir, initial-cluster-state, listen-peer-urls, listen-client-urls, certificate-related arguments.
​
cluster.etcd.advertisedSubnets
array
Subnet CIDRs to use for advertising etcd endpoints.

​
CoreDNS

​
cluster.coreDNS
object
CoreDNS configuration.
cluster:
  coreDNS:
    disabled: false
    image: registry.k8s.io/coredns/coredns:v1.11.1
​
cluster.coreDNS.disabled
boolean
default:"false"
Disable CoreDNS deployment on cluster bootstrap.
​
cluster.coreDNS.image
string
The CoreDNS container image to use.

​
Cluster Discovery

​
cluster.discovery
object
Cluster member discovery configuration.
cluster:
  discovery:
    enabled: true
    registries:
      service:
        endpoint: https://discovery.talos.dev
​
cluster.discovery.enabled
boolean
default:"true"
Enable cluster member discovery.
​
cluster.discovery.registries.service.endpoint
string
Discovery service endpoint.

​
Secrets and Certificates

​
cluster.token
string
The bootstrap token used to join the cluster. Format: <token-id>.<token-secret>.
​
cluster.ca
object
required
The base64 encoded root certificate authority used by Kubernetes.
​
cluster.aggregatorCA
object
The base64 encoded aggregator certificate authority used by Kubernetes for front-proxy certificate generation.
​
cluster.serviceAccount
object
The base64 encoded private key for service account token generation.
cluster:
  token: "abcdef.0123456789abcdef"
  ca:
    crt: LS0tLS1CRUdJTi...
    key: LS0tLS1CRUdJTi...
  aggregatorCA:
    crt: LS0tLS1CRUdJTi...
    key: LS0tLS1CRUdJTi...
  serviceAccount:
    key: LS0tLS1CRUdJTi...

​
Encryption at Rest

​
cluster.aescbcEncryptionSecret
string
A key used for encryption of secret data at rest. Enables encryption with AESCBC.
​
cluster.secretboxEncryptionSecret
string
A key used for encryption of secret data at rest. Enables encryption with secretbox. Secretbox has precedence over AESCBC.
cluster:
  secretboxEncryptionSecret: z01mye6j16bspJYtTB/5SFX8j7Ph4JXxM2Xuu4vsBPM=

​
Extra Manifests

​
cluster.extraManifests
array
A list of URLs that point to additional Kubernetes manifests. These are automatically deployed as part of the bootstrap.
​
cluster.extraManifestHeaders
object
A map of key-value pairs added as headers when fetching extra manifests.
cluster:
  extraManifests:
    - https://raw.githubusercontent.com/example/manifests/app.yaml
  extraManifestHeaders:
    Authorization: "Bearer token123"

​
Inline Manifests

​
cluster.inlineManifests
array
A list of inline Kubernetes manifests. These are automatically deployed as part of the bootstrap.
cluster:
  inlineManifests:
    - name: namespace-ci
      contents: |
        apiVersion: v1
        kind: Namespace
        metadata:
          name: ci

​
Admin Kubeconfig

​
cluster.adminKubeconfig
object
Settings for admin kubeconfig generation.
cluster:
  adminKubeconfig:
    certLifetime: 24h
​
cluster.adminKubeconfig.certLifetime
duration
default:"8760h"
Certificate lifetime for admin kubeconfig. Default is 1 year.

​
Allow Scheduling on Control Planes

​
cluster.allowSchedulingOnControlPlanes
boolean
default:"false"
Allows running workload on control plane nodes.
Enabling this removes the node-role.kubernetes.io/control-plane:NoSchedule taint from control plane nodes.
cluster:
  allowSchedulingOnControlPlanes: true

​
Complete Example

cluster:
  id: YWJjZGVmZ2hpamtsbW5vcA==
  secret: cXJzdHV2d3h5ejEyMzQ1Ng==
  clusterName: production
  controlPlane:
    endpoint: https://api.cluster.example.com:6443
    localAPIServerPort: 6443
  network:
    cni:
      name: custom
      urls:
        - https://raw.githubusercontent.com/cilium/cilium/v1.15.0/install/kubernetes/quick-install.yaml
    dnsDomain: cluster.local
    podSubnets:
      - 10.244.0.0/16
    serviceSubnets:
      - 10.96.0.0/12
  token: abcdef.0123456789abcdef
  ca:
    crt: LS0tLS1CRUdJTi...
    key: LS0tLS1CRUdJTi...
  apiServer:
    image: registry.k8s.io/kube-apiserver:v1.30.0
    extraArgs:
      feature-gates: ServerSideApply=true
    certSANs:
      - api.cluster.example.com
      - 192.168.1.100
  controllerManager:
    image: registry.k8s.io/kube-controller-manager:v1.30.0
  scheduler:
    image: registry.k8s.io/kube-scheduler:v1.30.0
  etcd:
    image: gcr.io/etcd-development/etcd:v3.5.13
    extraArgs:
      election-timeout: "5000"
  coreDNS:
    image: registry.k8s.io/coredns/coredns:v1.11.1
  discovery:
    enabled: true
  allowSchedulingOnControlPlanes: false

Build docs developers (and LLMs) love

Get started for freeTalk to us