talos-terraform

talos-terraform — Terraform Provider

For CLI operations see talosctl. For machine config YAML see talosconfig.

Provider: siderolabs/talos Latest stable: v0.11.0 (2026-04-27) — SDK targets Talos v1.13 config line Next (alpha): v0.12.0-alpha.x (2026-06-25) — adds talos_machine/talos_cluster, based on Talos v1.14. NOT stable.

Provider Setup

terraform {
  required_providers {
    talos = {
      source  = "siderolabs/talos"
      version = "~> 0.11.0"   # stable
    }
  }
}

Sidero-Blessed Production Pattern

Production-proven pattern for managing an EXISTING Talos cluster with Terraform. Core idea: generate config from live cluster secrets + patch files, apply with the stable talos_machine_configuration_apply resource, and let a separate system own OS/K8s upgrades.

Why NOT talos_machine (alpha)

talos_machine exists only in v0.12.0-alpha. It has a Create/Update bug with image = null — Optional+Computed fields plan as Unknown, and the provider attempts an upgrade with an empty image ref. If OS upgrades are owned elsewhere (e.g. tuppr TalosUpgrade CRs), avoid talos_machine entirely.

Architecture

locals (node map + live secrets + talosconfig)
  → data talos_machine_configuration (per node: live secrets + patch file)
    → resource talos_machine_configuration_apply (apply config to node)
      → apply_mode = staged_if_needing_reboot
      → lifecycle prevent_destroy

The Pattern

# 1. Cluster secrets from the LIVE cluster — NEVER regenerate.
#    Regenerating rotates all certs. Extracted once, gitignored.
locals {
  cluster_secrets = jsondecode(file("${path.module}/local_cluster_secrets.json"))
}

# 2. Client config from the cluster's talosconfig (os:admin).
#    certs.os = machine CA (for config gen) — NOT a valid apid client.
#    apid RBAC requires subject O=os:admin.
locals {
  talos_cfg = yamldecode(file("${path.module}/talosconfig.yaml"))
  talos_client_config = {
    ca_certificate     = local.talos_cfg.contexts[local.talos_cfg.context].ca
    client_certificate = local.talos_cfg.contexts[local.talos_cfg.context].crt
    client_key         = local.talos_cfg.contexts[local.talos_cfg.context].key
  }
}

# 3. Generate machine config per node: live secrets + version contract +
#    the applied config as patch (byte-exact reproduction of node state).
data "talos_machine_configuration" "node" {
  for_each = local.nodes

  cluster_name       = var.cluster_name
  cluster_endpoint   = each.value.endpoint
  machine_type       = each.value.role          # controlplane | worker
  machine_secrets    = local.cluster_secrets
  kubernetes_version = each.value.kubernetes_version
  talos_version      = each.value.talos_version  # RECOMMENDED: pin it

  config_patches = [file("${path.module}/patches/${each.key}-apply.yaml")]
}

# 4. Apply config — config-only, no OS version sync.
resource "talos_machine_configuration_apply" "node" {
  for_each = local.nodes

  node                        = each.value.ip
  client_configuration        = local.talos_client_config
  machine_configuration_input = data.talos_machine_configuration.node[each.key].machine_configuration
  apply_mode                  = "staged_if_needing_reboot"

  lifecycle {
    prevent_destroy = true   # live nodes: reconcile config only, never recreate
  }
}