Terraform for Talos Linux: Immutable Kubernetes Nodes

Talos Linux is an immutable, API-driven Kubernetes OS: no SSH, no shell, no package manager — only talosctl. The siderolabs/talos Terraform provider generates and applies machine configs. Combined with aws_instance (or vSphere / Proxmox), Terraform fully bootstraps a cluster.

Provider

#

terraform {
  required_providers {
    talos = {
      source  = "siderolabs/talos"
      version = "~> 0.7"
    }
  }
}

Generate Cluster Secrets and Configs

#

resource "talos_machine_secrets" "this" {}
 
data "talos_machine_configuration" "controlplane" {
  cluster_name     = var.cluster_name
  machine_type     = "controlplane"
  cluster_endpoint = "https://${aws_lb.cp.dns_name}:6443"
  machine_secrets  = talos_machine_secrets.this.machine_secrets
}
 
data "talos_machine_configuration" "worker" {
  cluster_name     = var.cluster_name
  machine_type     = "worker"
  cluster_endpoint = "https://${aws_lb.cp.dns_name}:6443"
  machine_secrets  = talos_machine_secrets.this.machine_secrets
}

Apply to Nodes

#

resource "talos_machine_configuration_apply" "cp" {
  for_each = aws_instance.controlplane
 
  client_configuration        = talos_machine_secrets.this.client_configuration
  machine_configuration_input = data.talos_machine_configuration.controlplane.machine_configuration
  node                        = each.value.private_ip
}
 
resource "talos_machine_bootstrap" "this" {
  depends_on = [talos_machine_configuration_apply.cp]
 
  client_configuration = talos_machine_secrets.this.client_configuration
  node                 = aws_instance.controlplane["0"].private_ip
}
 
data "talos_cluster_kubeconfig" "this" {
  client_configuration = talos_machine_secrets.this.client_configuration
  node                 = aws_instance.controlplane["0"].private_ip
 
  depends_on = [talos_machine_bootstrap.this]
}

Best Practices

#

• Use the Sidero Talos AMIs rather than building from scratch — saves the kernel signing pain.
• Three control planes across AZs — Talos doesn't tolerate split brain better than upstream Kubernetes.
• Store the kubeconfig in HCP Vault Secrets, not git.
• Upgrade with talos_machine_upgrade — never SSH (you can't anyway).
• Pair with Cilium (built-in via Talos config) for the strongest security default.

Frequently asked questions

#

How does Terraform bootstrap a Talos Kubernetes cluster?

#

The flow is: talos_machine_secrets generates the PKI, talos_machine_configuration (data source) renders control-plane and worker configs, talos_machine_configuration_apply pushes them to each node, talos_machine_bootstrap initializes etcd on the first control plane, and talos_cluster_kubeconfig returns the kubeconfig — all in one terraform apply.

Can I SSH into Talos Linux nodes?

#

No. Talos is intentionally immutable and API-only — there is no SSH, shell, or package manager. You manage nodes exclusively through talosctl (or the siderolabs/talos Terraform provider), which is what makes it so secure and reproducible.

How do I get the kubeconfig from Terraform?

#

Use the talos_cluster_kubeconfig data source with a depends_on the bootstrap resource. Write its output to a file with a local_file resource (or pull it into your CI), but store the long-lived copy in a secrets manager rather than committing it.

How do I upgrade Talos nodes with Terraform?

#

Use the talos_machine_upgrade resource pointing at the target image version. Talos performs an atomic A/B upgrade and reboots into the new image — never attempt an in-place package upgrade (there's no package manager to do it).

#

• Terraform Kubernetes Provider Guide
• Terraform for Bottlerocket OS on EKS
• Terraform for Proxmox VE
• Terraform for VMware vSphere / ESXi