hcloud-talos Terraform Module

The module supports several networking patterns for accessing the Kubernetes API and Talos API:

VPN-only (Private bootstrap with WireGuard)

Uses Talos's built-in WireGuard to manage the cluster over private IPs. Requires applying a WireguardConfig patch to the control plane and configuring a WireGuard client on your workstation.

VPN-only (Site-to-site VPN gateway)

Used when a VPN gateway VM exists on the same private network. Use cluster_api_host_private to point to the private VIP.

Fully Private (No public IPv4)

Nodes have no public IPs. All operations use private IPs via WireGuard or a VPN gateway. Set disable_public_ipv4 = true.

Floating IP (Public VIP)

Provides a stable public Kubernetes API endpoint without a dedicated load balancer. Set enable_floating_ip = true.

External TCP Load Balancer

Recommended for High Availability (HA). Points cluster_api_host to the Load Balancer DNS/IP and sets kubeconfig_endpoint_mode = "public_endpoint".

Split-horizon

Nodes use a private VIP/hostname, but the kubeconfig points to a public DNS/LB. Uses enable_alias_ip = true and cluster_api_host_private.

The module allows you to define how the Kubernetes and Talos APIs are accessed.

Public API Endpoint (Kubernetes API)

Use the cluster_api_host variable to define a stable public hostname (e.g., kube.mydomain.com).

• Requirement: You must create a DNS A record for this hostname pointing to the public IP (e.g., a Hetzner Floating IP or an external TCP load balancer).
• Kubeconfig: If kubeconfig_endpoint_mode = "public_endpoint" is set, the generated kubeconfig will use this hostname.
• Note: This controls the Kubernetes API (TCP/6443).

Internal API Endpoint (Node-to-Node)

Talos uses an internal hostname for communication between nodes. By default, this is kube.[cluster_domain] (e.g., kube.cluster.local).

• Override: Use cluster_api_host_private to change this.
• Alias IP: If enable_alias_ip = true (default), the module configures /etc/hosts on each node to resolve the internal hostname to a private alias IP (default 10.0.1.100).
• Split-Horizon DNS: If accessing the cluster via VPN, consider setting cluster_api_host_private to a resolvable private name (e.g., kube.example.com -> 10.0.1.100) to prevent client-side DNS failures.

Private Bootstrap

If running Terraform from a host with VPN/private network access (e.g., WireGuard, Tailscale), set bootstrap_endpoint_mode = "private_ip". This allows Terraform to bootstrap and health-check the cluster via private IPs instead of public ones. This can be combined with disable_public_ipv4 = true to provision nodes without any public IPv4 addresses.

This example demonstrates running the local module using terraform-provider-imager to create a Talos snapshot, which is then passed to the module via the talos_image_id_x86 variable.

Prerequisites

1. 1Password Configuration: Set the 1Password provider token using the environment variable TF_VAR_op_service_account_token_test. Alternatively, you can replace the 1Password configuration with direct hcloud and imager credentials.
2. Variable Setup: Copy terraform.tfvars.example to terraform.tfvars and populate it with your specific vault and item UUIDs.

Execution Steps

1. Initialize the working directory:

   terraform init

2. Apply the configuration. Note that the initial terraform apply may take several minutes because it must upload the Talos disk image to Hetzner Cloud and create a snapshot.

   terraform apply

3. Export the generated credentials to local files:

   terraform output --raw kubeconfig > ./kubeconfig
   terraform output --raw talosconfig > ./talosconfig

The recommended way to prepare Talos OS images for Hetzner Cloud is using the hcloud-talos/imager provider. This avoids issues with official Hetzner Talos ISOs, which may boot in metal mode instead of hcloud mode, causing incorrect providerIDs and networking failures.

To use this workflow:

1. Configure the imager provider with your hcloud_token.
2. Define an imager_image resource using a Talos Factory URL.
3. Pass the resulting snapshot IDs into the hcloud-talos module using talos_image_id_x86 and/or talos_image_id_arm.

terraform {
  required_providers {
    imager = {
      source = "hcloud-talos/imager"
    }
  }
}

provider "imager" {
  token = var.hcloud_token
}

resource "imager_image" "talos_x86" {
  image_url    = "https://factory.talos.dev/image/<schematic-id>/<talos-version>/hcloud-amd64.raw.xz"
  architecture = "x86"

  labels = {
    version = var.talos_version
  }
}

Deploy a Kubernetes cluster running Talos OS on Hetzner Cloud using the hcloud-talos/talos/hcloud module.

Key Configuration Notes:

• Version Compatibility: Ensure talos_version, kubernetes_version, and cilium_version are compatible with each other and the Talos Support Matrix.
• Firewall Access: If firewall_use_current_ip is true, the module fetches your public IP via https://ipv4.icanhazip.com to allow API access. If false, you must manually provide IPs in firewall_kube_api_source and firewall_talos_api_source.
• Node Definitions: Define control_plane_nodes and worker_nodes as lists of objects specifying id and type (e.g., cax11).

module "talos" {
  source  = "hcloud-talos/talos/hcloud"
  version = "<latest-version>"

  talos_version      = "v1.12.2"
  kubernetes_version = "1.35.0"
  cilium_version     = "1.16.2"

  hcloud_token = "your-hcloud-token"

  cluster_name     = "dummy.com"
  cluster_domain   = "cluster.dummy.com.local"
  cluster_api_host = "kube.dummy.com"

  firewall_use_current_ip  = false
  firewall_kube_api_source = ["your-ip"]
  firewall_talos_api_source = ["your-ip"]

  location_name = "fsn1"

  control_plane_nodes = [
    { id = 1, type = "cax11" },
    { id = 2, type = "cax11" },
    { id = 3, type = "cax11" }
  ]
  control_plane_allow_schedule = true

  worker_nodes = [
    { id = 1, type = "cax21" },
    { id = 2, type = "cax21" },
    { id = 3, type = "cax21" }
  ]

  network_ipv4_cidr = "10.0.0.0/16"
  node_ipv4_cidr    = "10.0.1.0/24"
  pod_ipv4_cidr     = "10.0.16.0/20"
  service_ipv4_cidr = "10.0.8.0/21"
  
  tailscale = {
    enabled  = true
    auth_key = "tskey-auth-xxxxxxxxxxxx"
  }
}