Configuration

A cluster directory holds two files that taloscluster reads together. cluster.yaml describes the desired state and is safe to commit. secrets.yaml holds credentials and is gitignored. taloscluster init [--openstack|--proxmox] NAME scaffolds both, and the core loader validates required fields and supported values. A top-level key neither core nor an installed plugin owns is refused — a misspelled or unsupported section is caught instead of silently ignored. A miscapped or unsupported key inside a fixed-schema section is refused too, including in nested fixed-schema blocks such as proxmox.network — talos.extensons, network.dnss, openstack.regoin or proxmox.network.clustr no longer load quietly (a typo like openstack.regoin used to silently fall back to the RegionOne default). Freeform maps are left open: cluster and pool tags are arbitrary label maps, security host labels are free-form, and config_patches hold arbitrary YAML. Sections owned by an installed plugin (e.g. argocd, rancher) are retained as valid; each plugin's validate hook runs in converge's validate phase for every installed plugin before any mutation, so a malformed or contradictory plugin section is refused up front instead of being checked only when the plugin's hooks run later.

All example addresses and hostnames in these pages are placeholders (RFC 5737 documentation ranges and example.edu).

cluster.yaml

Key	Required	What it is	Details
name	yes	Cluster name, prefix of every hostname	General
tags	no	Extra Kubernetes node labels for every node	General
talos	yes	Talos version, extra extensions, machine-config patches	General
kubernetes	yes	Kubernetes version	General
controlplane	yes	Control plane pool: count and sizing	Pools
workers	no	Worker pools by name: count, sizing, extensions, tags	Pools
openstack	one of	OpenStack endpoint, availability zone, external network, optional region	OpenStack
proxmox	one of	Proxmox endpoint, storages, placement, networks	Proxmox
network	yes	Private CIDR, DNS and NTP servers	Network
security	no	Named ingress allowlists per port	Security
tailscale	no	Opt into the tailscale extension, login server	Tailscale
rancher	no	Rancher plugin: members to grant access	Rancher
argocd	no	ArgoCD plugin: project roles, repositories, per-app settings	ArgoCD

Exactly one of openstack or proxmox must be present. It selects the backend and decides which pool sizing keys are required.

Minimal Proxmox example:

name: mycluster

talos:
  version: v1.13.8
kubernetes:
  version: v1.36.1

controlplane:
  count: 3
  cores: 4
  memory: 8
  disk: 40

workers:
  worker:
    count: 3
    cores: 8
    memory: 16
    disk: 100

proxmox:
  url: https://pve.example.edu:8006
  storage: local-lvm
  iso_storage: local
  network:
    cluster:
      bridge: vmbr0
      kubeapi_vip: 10.0.0.10

network:
  cidr: 10.0.0.0/24
  dns: [192.0.2.53]
  ntp: [ntp.example.edu]

security:
  kubernetes:
    office vpn: 198.51.100.0/24
  talos:
    office vpn: 198.51.100.0/24

secrets.yaml

Never commit this file. taloscluster init writes it with mode 0600 and adds it to .gitignore. The provider block must match the provider chosen in cluster.yaml, and the other provider's block may not be present. Each credential value must be a real, non-empty string: a null, non-string, or still-scaffolded CHANGE-ME placeholder is refused at secrets load time (see init and the provider/Tailscale pages) instead of failing later as an opaque 401.

Key	Required	What it is	Details
openstack	on OpenStack	Application credential id and secret	OpenStack
proxmox	on Proxmox	API token id and secret	Proxmox
tailscale	no	Pre-auth key nodes register with	Tailscale
rancher	no	Rancher server URL and token	Rancher
argocd	no	How to reach the ArgoCD cluster	ArgoCD

proxmox:
  token_id: "taloscluster@pve!provider"
  token_secret: "CHANGE-ME"

tailscale:
  auth_key: "CHANGE-ME"

Other files in the directory

talossecrets.yaml is the cluster's cryptographic identity, generated on the first converge and gitignored. It cannot be regenerated for a running cluster, so back it up out of band. talosconfig is derived from it and refreshed by converge. kubeconfig is fetched during bootstrap or an API endpoint move and is otherwise retained. Keep both client files with the cluster directory, especially when moving the API endpoint.