### Example Compatible Version Set

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/best-practices.md

An example of a compatible set of Talos, Kubernetes, and Cilium versions. Ensure these versions align with the latest stable and supported releases.

```hcl
talos_version      = "v1.12.2"   # Latest stable
kubernetes_version = "1.35.0"    # Supported by Talos v1.12.2
cilium_version     = "1.16.2"    # Compatible with K8s 1.35.0
```

--------------------------------

### Multi-Architecture Cluster Setup

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/api-reference.md

Example configuration for a cluster supporting multiple architectures (x86 and ARM64). Control plane nodes are x86, while worker nodes include both x86 and ARM64 instances.

```hcl
control_plane_nodes = [
  { id = 1, type = "cx33" }  # x86
]
worker_nodes = [
  { id = 1, type = "cx43" },    # x86
  { id = 2, type = "cax21" }    # ARM64
]
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/CONTRIBUTING.md

Install pre-commit hooks for formatting, validation, and security checks, as well as a commit-msg hook for validating commit messages.

```bash
pre-commit install
pre-commit install --hook-type commit-msg
```

--------------------------------

### Complete Talos Cluster Configuration Example

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/configuration.md

A comprehensive example demonstrating the configuration of a Talos Kubernetes cluster on Hetzner Cloud, including authentication, cluster identity, infrastructure, networking, nodes, and add-ons.

```hcl
module "talos" {
  source = "hcloud-talos/talos/hcloud"
  version = "~> 1.0"

  # Authentication
  hcloud_token = var.hcloud_token

  # Cluster identity
  cluster_name    = "prod-cluster"
  cluster_domain  = "k8s.example.local"
  cluster_api_host = "kube.example.com"
  cluster_api_host_private = "kube.internal.example.com"

  # Infrastructure
  location_name = "fsn1"

  # Versions
  talos_version      = "v1.12.2"
  kubernetes_version = "1.35.0"

  # Networking
  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"

  enable_floating_ip = true
  enable_alias_ip    = true

  # Access
  firewall_use_current_ip    = true
  kubeconfig_endpoint_mode   = "public_endpoint"
  talosconfig_endpoints_mode = "public_ip"

  # Nodes
  control_plane_nodes = [
    { id = 1, type = "cx33" },
    { id = 2, type = "cx33" },
    { id = 3, type = "cx33" }
  ]

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

  control_plane_allow_schedule = false

  # Talos configuration
  talos_version = "v1.12.2"
  talos_image_id_x86 = "123456"

  kubelet_extra_args = {
    "system-reserved" = "cpu=100m,memory=250Mi"
  }

  sysctls_extra_args = {
    "net.core.rmem_default" = "26214400"
  }

  # Container registry
  registries = {
    mirrors = {
      "docker.io" = {
        endpoints = ["http://registry-cache:5000"]
      }
    }
  }

  # CNI and add-ons
  cilium_version            = "1.16.2"
  cilium_enable_encryption  = false
  deploy_cilium             = true
  deploy_hcloud_ccm         = true
  deploy_prometheus_operator_crds = false

  # Tailscale optional
  tailscale = {
    enabled  = false
    auth_key = ""
  }
}
```

--------------------------------

### Network Route Configuration Example

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/types.md

Example of configuring multiple network routes for VPN site-to-site connections. This adds static routes for different subnets to the cloud network.

```hcl
network_routes = [
  {
    destination = "10.8.0.0/24"
    gateway     = "10.0.1.250"
  },
  {
    destination = "10.9.0.0/24"
    gateway     = "10.0.1.250"
  }
]
```

--------------------------------

### Basic Example

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/api-reference.md

A minimal configuration for deploying a single control plane node Kubernetes cluster using the Talos module on Hetzner Cloud.

```hcl
module "talos" {
  source  = "hcloud-talos/talos/hcloud"
  version = "~> 1.0"

  hcloud_token = var.hcloud_token
  
  talos_version      = "v1.12.2"
  kubernetes_version = "1.35.0"
  
  cluster_name  = "my-cluster"
  location_name = "fsn1"
  
  firewall_use_current_ip = true
  
  control_plane_nodes = [
    {
      id   = 1
      type = "cx33"
    }
  ]
}
```

--------------------------------

### Control Plane Node Configuration Example

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/types.md

Example of how to configure multiple control plane nodes, specifying their IDs, server types, and optionally applying labels or taints.

```hcl
control_plane_nodes = [
  {
    id   = 1
    type = "cx33"
    labels = {
      "node-role.kubernetes.io/master" = "true"
    }
  },
  {
    id   = 2
    type = "cx33"
  },
  {
    id    = 3
    type   = "cx33"
    taints = [
      {
        key    = "role"
        value  = "control-plane"
        effect = "NoSchedule"
      }
    ]
  }
]
```

--------------------------------

### Floating IP Configuration Example

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/types.md

Example of specifying an existing Floating IP to be used by the module. This ensures a specific IP address is assigned.

```hcl
floating_ip = {
  id = 12345678
}
```

--------------------------------

### Worker Node Configuration Example

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/types.md

Example of configuring worker nodes with specific server types, labels, and taints. This demonstrates assigning a workload type label and an architecture taint.

```hcl
worker_nodes = [
  {
    id   = 1
    type = "cx43"
    labels = {
      "workload-type" = "general"
    }
  },
  {
    id    = 2
    type   = "cax21"
    labels = {
      "node.kubernetes.io/arch" = "arm64"
    }
    taints = [
      {
        key    = "arch"
        value  = "arm64"
        effect = "NoSchedule"
      }
    ]
  }
]
```

--------------------------------

### Conventional Commit Message Format Example

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/CONTRIBUTING.md

An example demonstrating the Conventional Commits format, including type, scope, description, body, and footer types like BREAKING CHANGE and Closes.

```git
feat(network): add support for IPv6 alias IPs

Add configuration option to enable IPv6 on alias IPs for control plane
high availability setups.

BREAKING CHANGE: The `enable_alias_ip` variable now requires explicit
IPv6 configuration.
Closes #123
```

--------------------------------

### Transition Talos Cluster Add-ons from Terraform to GitOps

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/examples-and-patterns.md

Illustrates a phased approach to managing cluster add-ons, starting with Terraform and transitioning to a GitOps tool like ArgoCD or Flux. This involves toggling Terraform management off and letting GitOps take over.

```hcl
# Phase 1: Initial deployment (terraform deploy phase)
module "talos" {
  source  = "hcloud-talos/talos/hcloud"
  version = "~> 1.0"

  # ... cluster config ...
  
  deploy_cilium                = true
  deploy_hcloud_ccm            = true
  deploy_prometheus_operator_crds = true
}

# Phase 2: After cluster bootstrap, transition to GitOps
# Update to:
module "talos" {
  source  = "hcloud-talos/talos/hcloud"
  version = "~> 1.0"

  # ... cluster config ...
  
  # Set to false to remove from Terraform state
  deploy_cilium                = false
  deploy_hcloud_ccm            = false
  deploy_prometheus_operator_crds = false
}

# Then run: terraform apply
# Resources are removed from state but not from cluster

# Phase 3: GitOps tool (ArgoCD/Flux) now manages these
# ArgoCD ApplicationSet watches the cluster and applies manifests
```

--------------------------------

### High-Availability Production Example

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/api-reference.md

A comprehensive configuration for a highly available production Kubernetes cluster with 3 control plane nodes and advanced networking options.

```hcl
module "talos" {
  source  = "hcloud-talos/talos/hcloud"
  version = "~> 1.0"

  hcloud_token = var.hcloud_token
  
  talos_version      = "v1.12.2"
  kubernetes_version = "1.35.0"
  cilium_version     = "1.16.2"
  
  cluster_name            = "prod-cluster"
  cluster_domain          = "k8s.example.local"
  cluster_api_host        = "kube.example.com"
  cluster_api_host_private = "kube.internal.example.com"
  
  location_name = "fsn1"
  
  # Network configuration
  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"
  
  # High Availability
  enable_floating_ip         = true
  enable_alias_ip            = true
  kubeconfig_endpoint_mode   = "public_endpoint"
  talosconfig_endpoints_mode = "public_ip"
  
  # Firewall
  firewall_use_current_ip = true
  
  # 3-node control plane
  control_plane_nodes = [
    { id = 1, type = "cx33" },
    { id = 2, type = "cx33" },
    { id = 3, type = "cx33" }
  ]
  
  # Worker nodes
  worker_nodes = [
    { id = 1, type = "cx43" },
    { id = 2, type = "cx43" }
  ]
  
  # Talos OS configuration
  sysctls_extra_args = {
    "net.core.rmem_default" = "26214400"
    "net.core.wmem_default" = "26214400"
  }
  
  # Add-ons
  cilium_enable_encryption  = false
  deploy_cilium             = true
  deploy_hcloud_ccm         = true
  deploy_prometheus_operator_crds = false
}
```

--------------------------------

### Minimal Terraform Example

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/README.md

A basic Terraform configuration to deploy a single control plane Talos Kubernetes cluster on Hetzner Cloud. It requires Hetzner Cloud API token, Talos and Kubernetes versions, cluster name, location, and specifies the control plane node type.

```hcl
module "talos" {
  source  = "hcloud-talos/talos/hcloud"
  version = "~> 1.0"

  hcloud_token       = var.hcloud_token
  talos_version      = "v1.12.2"
  kubernetes_version = "1.35.0"
  cluster_name       = "my-cluster"
  location_name      = "fsn1"
  
  firewall_use_current_ip = true
  
  control_plane_nodes = [
    { id = 1, type = "cx33" }
  ]
}

output "kubeconfig" {
  value     = module.talos.kubeconfig
  sensitive = true
}

output "talosconfig" {
  value     = module.talos.talosconfig
  sensitive = true
}
```

--------------------------------

### Add Custom Firewall Rule

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/outputs.md

Example of adding a custom firewall rule to the cluster's firewall using the outputted firewall ID.

```hcl
resource "hcloud_firewall_rule" "custom" {
  firewall_id = module.talos.firewall_id
  
  direction   = "in"
  protocol    = "tcp"
  port        = "8080"
  source_ips  = ["0.0.0.0/0"]
}
```

--------------------------------

### Terraform Variables for Hcloud Talos Module

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/examples-and-patterns.md

Provides example values for the Terraform variables required by the Hcloud Talos module, including Hetzner Cloud token and container registry credentials.

```hcl
hcloud_token         = "your-hcloud-token"
registry_username    = "myuser"
registry_password    = "mypassword"
```

--------------------------------

### HA Production with DNS and Load Balancer

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/api-reference.md

Setup for a highly available production cluster using a custom domain name and an external TCP load balancer. The `kubeconfig_endpoint_mode` is set to `public_endpoint` to utilize the specified `cluster_api_host`.

```hcl
cluster_api_host = "kube.example.com"  # Point to your TCP LB
kubeconfig_endpoint_mode = "public_endpoint"

control_plane_nodes = [
  { id = 1, type = "cx33" },
  { id = 2, type = "cx33" },
  { id = 3, type = "cx33" }
]
```

--------------------------------

### Deploy Mixed Architecture Cluster

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/examples-and-patterns.md

Configure a cluster with both x86 and ARM nodes to accommodate diverse workload requirements. This setup allows for flexible placement of applications based on their architecture and performance needs. Ensure your Kubernetes workloads utilize node selectors and tolerations to target specific node types.

```hcl
module "talos" {
  source  = "hcloud-talos/talos/hcloud"
  version = "~> 1.0"

  hcloud_token = var.hcloud_token
  
  talos_version      = "v1.12.2"
  kubernetes_version = "1.35.0"
  
  cluster_name  = "mixed-arch"
  location_name = "fsn1"
  
  firewall_use_current_ip = true
  
  # 3-node control plane (x86)
  control_plane_nodes = [
    {
      id   = 1
      type = "cx33"
      labels = {
        "arch" = "x86"
      }
    },
    {
      id   = 2
      type = "cx33"
      labels = {
        "arch" = "x86"
      }
    },
    {
      id   = 3
      type = "cx33"
      labels = {
        "arch" = "x86"
      }
    }
  ]
  
  # Mixed worker nodes
  worker_nodes = [
    {
      id   = 1
      type = "cx43"
      labels = {
        "workload-type" = "general"
        "arch"          = "x86"
      }
    },
    {
      id   = 2
      type = "cx43"
      labels = {
        "workload-type" = "general"
        "arch"          = "x86"
      }
    },
    {
      id   = 3
      type = "cax21"
      labels = {
        "workload-type" = "arm-intensive"
        "arch"          = "arm64"
      }
      taints = [
        {
          key    = "arch"
          value  = "arm64"
          effect = "NoSchedule"
        }
      ]
    },
    {
      id   = 4
      type = "cax41"
      labels = {
        "workload-type" = "high-performance"
        "arch"          = "arm64"
      }
      taints = [
        {
          key    = "workload"
          value  = "high-performance"
          effect = "NoSchedule"
        }
      ]
    }
  ]
  
  deploy_cilium     = true
  deploy_hcloud_ccm = true
}
```

```yaml
# x86 only
apiVersion: v1
kind: Pod
metadata:
  name: x86-app
spec:
  nodeSelector:
    arch: x86

---

# ARM64 only
apiVersion: v1
kind: Pod
metadata:
  name: arm-app
spec:
  nodeSelector:
    arch: arm64
  tolerations:
    - key: "arch"
      operator: "Equal"
      value: "arm64"
      effect: "NoSchedule"

---

# High-performance ARM64
apiVersion: v1
kind: Pod
metadata:
  name: high-perf-app
spec:
  nodeSelector:
    arch: arm64
    workload-type: high-performance
  tolerations:
    - key: "workload"
      operator: "Equal"
      value: "high-performance"
      effect: "NoSchedule"
```

--------------------------------

### Using kubectl and talosctl

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/api-reference.md

Demonstrates how to use the exported kubeconfig with kubectl and talosconfig with talosctl to interact with the cluster.

```bash
# Use with kubectl and talosctl
kubectl get nodes
talosctl -n <control-plane-ip> version
```

--------------------------------

### Initialize Terraform

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/examples/extended/README.md

Run this command to initialize the Terraform working directory. It downloads the necessary providers and modules.

```shell
terraform init
```

--------------------------------

### Transition to GitOps

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/README.md

Prepare the cluster for GitOps by disabling certain add-ons like Cilium and the Hetzner Cloud Controller Manager. Apply the changes using Terraform.

```bash
Set deploy_cilium = false, deploy_hcloud_ccm = false, etc. and run terraform apply.
```

--------------------------------

### Configure Kubelet Extra Arguments

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/configuration.md

Pass additional arguments to kubelet for system and kubelet reservations, and eviction policies. Each key-value pair becomes a `--key=value` flag.

```hcl
kubelet_extra_args = {
  "system-reserved"   = "cpu=100m,memory=250Mi"
  "kube-reserved"     = "cpu=100m,memory=200Mi"
  "eviction-hard"     = "memory.available<100Mi"
}
```

--------------------------------

### Disable Talos CoreDNS

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/configuration.md

Set to true to prevent Talos from deploying CoreDNS. Use this if you manage DNS separately, for example, with GitOps.

```hcl
disable_talos_coredns = false
```

--------------------------------

### Get Firewall ID

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/api-reference.md

Retrieve the firewall ID to check its rules and ensure proper network access to your cluster's APIs.

```bash
terraform output firewall_id
```

--------------------------------

### Get Network IPv4 CIDR

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/outputs.md

Retrieves the main network CIDR for the cluster. Returns the value of the `network_ipv4_cidr` variable, defaulting to `10.0.0.0/16`.

```bash
terraform output network_ipv4_cidr
# Output: "10.0.0.0/16"
```

--------------------------------

### Execute Packer Build Script

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/README.md

Run the create.sh script from the repository root to initiate the Packer build process for Talos OS snapshots. Ensure the HCLOUD_TOKEN environment variable is set.

```bash
./_packer/create.sh
```

--------------------------------

### Manage Worker Node RDNS Records

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/outputs.md

Example of using the `talos_worker_ids` output to manage reverse DNS (RDNS) records for worker nodes.

```hcl
locals {
  worker_server_ids = values(module.talos.talos_worker_ids)
}

resource "hcloud_rdns" "workers" {
  for_each = module.talos.talos_worker_ids
  
  server_id = each.value
  ip_address = hcloud_server.workers[each.key].ipv4_address
  dns_ptr    = "worker-${each.key}.example.com"
}
```

--------------------------------

### Build Default Talos Images for Hetzner Cloud

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_packer/README.md

Execute this script to build the standard Talos OS images (ARM and x86) for Hetzner Cloud. It checks for Packer, prompts for API token if needed, initializes Packer, and runs the build process using default image URLs.

```bash
./create.sh

```

--------------------------------

### Get Network Subnet ID

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/outputs.md

Retrieves the ID of the Hetzner Cloud network subnet created by the module. Returns `null` if an existing network was provided.

```bash
terraform output network_subnet_id
# Output: "12346" (or null if using existing network)
```

--------------------------------

### Configure Kubelet Extra Arguments

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/README.md

Set additional arguments for Kubelet, including system and kube reservations, and eviction policies.

```hcl
kubelet_extra_args = {
  system-reserved            = "cpu=100m,memory=250Mi,ephemeral-storage=1Gi"
  kube-reserved              = "cpu=100m,memory=200Mi,ephemeral-storage=1Gi"
  eviction-hard              = "memory.available<100Mi,nodefs.available<10%"
  eviction-soft              = "memory.available<200Mi,nodefs.available<15%"
  eviction-soft-grace-period = "memory.available=2m30s,nodefs.available=4m"
}
```

--------------------------------

### Get Hetzner Network ID

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/outputs.md

Retrieves the ID of the Hetzner Cloud network used by the cluster. Useful for attaching resources to the same network or for cross-module references.

```bash
terraform output hetzner_network_id
# Output: 12345
```

--------------------------------

### Load Kernel Modules at Boot

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/types.md

Specify kernel modules to be loaded during node boot, including optional parameters. Used by the 'kernel_modules_to_load' variable.

```hcl
kernel_modules_to_load = [
  {
    name = "binfmt_misc"
  },
  {
    name       = "nf_conntrack"
    parameters = ["hashsize=262144"]
  }
]
```

--------------------------------

### Get Firewall ID

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/outputs.md

Retrieves the ID of the Hetzner Cloud firewall attached to cluster nodes. Useful for adding external firewall rules or for cross-module references.

```bash
terraform output firewall_id
# Output: "12347"
```

--------------------------------

### Minimal RBAC ClusterRole

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/best-practices.md

Define a ClusterRole with minimal permissions, granting read-only access to pods and services. This is a starting point for restricting API access after cluster deployment.

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: minimal-access
rules:
  - apiGroups: [""]
    resources: ["pods", "services"]
    verbs: ["get", "list"]
```

--------------------------------

### Create Talos x86 Image with Terraform Imager Provider

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/README.md

This snippet demonstrates how to use the `imager` provider to create a custom Talos OS image for x86 architecture within your Hetzner Cloud project. Ensure you have the `hcloud-talos/imager` provider configured and a valid `hcloud_token`.

```hcl
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
  }
}
```

--------------------------------

### Activate Kernel Modules

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/README.md

Specify kernel modules to be loaded on the nodes, such as 'binfmt_misc' required for QEMU.

```hcl
kernel_modules_to_load = [
  {
    name = "binfmt_misc" # Required for QEMU
  }
]
```

--------------------------------

### Additional Network Routes Configuration

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/configuration.md

Add custom routes to the Hetzner Cloud network, useful for VPN site-to-site setups. Each route requires a destination CIDR and a gateway IP.

```hcl
network_routes = [
  {
    destination = "10.8.0.0/24"
    gateway     = "10.0.1.250"
  }
]
```

--------------------------------

### Use talosctl with exported config

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/outputs.md

Manage the cluster using talosctl with the exported Talos client configuration file.

```bash
talosctl --talosconfig ~/.talos/config version
talosctl --talosconfig ~/.talos/config status
```

--------------------------------

### External TCP Load Balancer Configuration

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/README.md

Configure Talos to use an external TCP (L4) load balancer for the Kubernetes API endpoint. Recommended for High Availability (HA) setups.

```hcl
firewall_use_current_ip    = true

cluster_api_host           = "kube.example.com" # -> LB IP/DNS
kubeconfig_endpoint_mode   = "public_endpoint"
talosconfig_endpoints_mode = "public_ip"
```

--------------------------------

### Export Talos and Kubeconfig to Files

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/outputs.md

Exports the Talos configuration and kubeconfig to local files, setting appropriate permissions. Verifies connectivity using `kubectl` and `talosctl`.

```bash
# Export talosconfig
terraform output --raw talosconfig > ~/.talos/config
chmod 600 ~/.talos/config

# Export kubeconfig
terraform output --raw kubeconfig > ~/.kube/config
chmod 600 ~/.kube/config

# Verify connectivity
kubectl get nodes
talosctl -n <control-plane-ip> version
```

--------------------------------

### Get Public IPv4 List

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/outputs.md

Retrieves a list of public IPv4 addresses for all control plane nodes. Useful for accessing specific nodes, configuring load balancers, or setting up DNS records.

```bash
terraform output public_ipv4_list
# Output: ["203.0.113.1", "203.0.113.2", "203.0.113.3"]
```

--------------------------------

### Enable Tailscale Integration

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/types.md

Configure Tailscale as a system extension on all nodes by setting enabled to true and providing an auth key. This is used by the 'tailscale' variable.

```hcl
tailscale = {
  enabled  = true
  auth_key = "tskey-auth-XXXXXXXXXXXX"
}
```

--------------------------------

### Programmatic Access to Cluster Data

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/outputs.md

Provides examples of using `jq` to programmatically extract specific data, such as control plane IPs, worker IDs, and kubeconfig host information, from Terraform outputs in JSON format.

```bash
# Get control plane IPs as JSON
terraform output -json public_ipv4_list | jq .

# Get worker IDs as JSON
terraform output -json talos_worker_ids | jq .

# Extract kubeconfig data
terraform output -json kubeconfig_data | jq '.host'
```

--------------------------------

### Add Extra Kubernetes Manifests

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/configuration.md

List of URLs to additional Kubernetes manifests to apply during Talos bootstrap.

```hcl
extraManifests = [
  "https://example.com/manifests/custom-app.yaml"
]
```

--------------------------------

### Get Node IPv4 CIDR

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/outputs.md

Retrieves the subnet CIDR used for control plane and worker nodes. Returns the value of the `node_ipv4_cidr` variable, defaulting to `10.0.1.0/24`. Useful for VPN route and firewall rule configuration.

```bash
terraform output node_ipv4_cidr
# Output: "10.0.1.0/24"
```

--------------------------------

### Post-Deployment Commands

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/README.md

Commands to export Kubernetes and Talos configuration files and set appropriate permissions. Verifies cluster status using kubectl and talosctl.

```bash
# Export configs
terraform output --raw kubeconfig > ~/.kube/config
terraform output --raw talosconfig > ~/.talos/config
chmod 600 ~/.kube/config ~/.talos/config

# Verify cluster
kubectl get nodes
talosctl version
```

--------------------------------

### Get Talos Worker IDs

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/outputs.md

Retrieves a map of worker node IDs to their Hetzner Cloud server IDs. The map keys correspond to the stable IDs from the `worker_nodes` configuration. Useful for correlating configuration with server IDs and managing worker nodes individually.

```bash
terraform output talos_worker_ids
# Output:
# {
#   "1" = "12348"
#   "2" = "12349"
# }
```

--------------------------------

### Troubleshoot Node Not Ready

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/best-practices.md

When nodes show as NotReady, describe the node and check system pods. Examine Talos logs for kubelet and controlplane errors. Common causes include network issues (Cilium) or resource constraints.

```bash
kubectl describe node <node-name>
kubectl get pods -n kube-system -o wide

# Check Talos logs
talosctl -n <node-ip> logs kubelet
talosctl -n <node-ip> logs controlplane
```

--------------------------------

### Export talosconfig to File

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/outputs.md

Export the Talos client configuration to a file and set appropriate permissions. This is necessary for using talosctl to manage the cluster.

```bash
terraform output --raw talosconfig > ~/.talos/config
chmod 600 ~/.talos/config
```

--------------------------------

### Check Talos, Kubernetes, and Cilium Version Compatibility

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/best-practices.md

Before deployment, verify that the versions of Talos, Kubernetes, and Cilium are compatible. Refer to the official support matrices for accurate compatibility information.

```bash
# Check compatibility matrix
# - Talos version
# - Kubernetes version  
# - Cilium version
# - All must be compatible

# Verify:
# 1. Talos support matrix: https://docs.siderlabs.com/talos/latest/getting-started/support-matrix
# 2. Cilium compatibility: https://docs.cilium.io/en/stable/network/kubernetes/compatibility/
```

--------------------------------

### Terraform Development Commands

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/CLAUDE.md

Common commands for formatting, initializing, validating, building, and deploying the Terraform module. Includes exporting configurations and accessing the cluster.

```bash
# Format and validate
terraform fmt -recursive
terraform init
terraform validate

# Build Talos images (REQUIRED before first deployment)
./_packer/create.sh

# Quality checks
pre-commit install
pre-commit run --all-files

# Deploy
terraform plan
terraform apply

# Export configs
terraform output --raw kubeconfig > ./kubeconfig
terraform output --raw talosconfig > ./talosconfig

# Access cluster
export KUBECONFIG=./kubeconfig
kubectl get nodes

# Talos management (use public endpoint)
talosctl --talosconfig ./talosconfig --endpoint <public-ip> version
```

--------------------------------

### Configure Sysctl Extra Arguments

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/README.md

Apply custom sysctl settings, such as network buffer sizes, to the nodes.

```hcl
sysctls_extra_args = {
  # Fix for https://github.com/cloudflare/cloudflared/issues/1176
  "net.core.rmem_default" = "26214400"
  "net.core.wmem_default" = "26214400"
  "net.core.rmem_max"     = "26214400"
  "net.core.wmem_max"     = "26214400"
}
```

--------------------------------

### Apply Terraform Configuration

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/examples/extended/README.md

Executes the Terraform plan and applies the changes to create or update infrastructure. This may take several minutes as it involves uploading a disk image and creating a snapshot.

```shell
terraform apply
```

--------------------------------

### Access Cluster Network Information

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/outputs.md

Demonstrates commands to retrieve public IP addresses, network IDs, and CIDR information for the cluster's network.

```bash
# Get all control plane public IPs
terraform output -json public_ipv4_list

# Get network details
terraform output hetzner_network_id
terraform output network_ipv4_cidr
terraform output node_ipv4_cidr

# Get firewall ID for additional rules
terraform output firewall_id
```

--------------------------------

### Configure Kube API Server Extra Arguments

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/configuration.md

Pass additional arguments to kube-apiserver. Each key-value pair becomes a `--key=value` flag.

```hcl
kube_api_extra_args = {
  "enable-aggregator-routing" = "true"
}
```

--------------------------------

### Configure Container Registry Mirrors and Authentication

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/types.md

Set up container registry mirrors with endpoints and optional path overrides, and configure authentication with username, password, or identity tokens. Used by the 'registries' variable.

```hcl
registries = {
  mirrors = {
    "docker.io" = {
      endpoints = [
        "http://localhost:5000",
        "https://registry-1.docker.io"
      ]
    }
    "gcr.io" = {
      endpoints = [
        "http://gcr-mirror:5000"
      ]
      overridePath = true
    }
  }
  config = {
    "my-registry.example.com" = {
      auth = {
        username = "myuser"
        password = "mypassword"
      }
    }
  }
}
```

--------------------------------

### Transition Add-ons to GitOps

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/api-reference.md

After initial cluster bootstrap, disable module-managed add-ons and apply Terraform once to transition to a GitOps workflow. The `apply_only = true` setting prevents Terraform from deleting these resources.

```hcl
deploy_cilium  = false
deploy_hcloud_ccm = false
deploy_prometheus_operator_crds = false
```

--------------------------------

### Kubelet Eviction Policies

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/best-practices.md

Configure hard and soft eviction thresholds for memory and node filesystem usage. This helps maintain node stability by proactively reclaiming resources when thresholds are breached.

```hcl
kubelet_extra_args = {
  "eviction-hard"   = "memory.available<100Mi,nodefs.available<10%"
  "eviction-soft"   = "memory.available<200Mi,nodefs.available<15%"
  "eviction-soft-grace-period" = "memory.available=2m30s,nodefs.available=4m"
}
```

--------------------------------

### Tune Kubelet for Performance

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/best-practices.md

Optimize Kubelet settings for better pod management and node status reporting. These arguments are passed via kubelet_extra_args.

```hcl
kubelet_extra_args = {
  "max-pods"                = "200"
  "node-status-update-frequency" = "10s"
  "volume-stats-agg-period" = "30s"
}
```

--------------------------------

### WireGuard Configuration for Workstation

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/README.md

Configure your workstation's WireGuard client to connect to the Talos cluster. This can be used with the macOS WireGuard app or `wg-quick`.

```ini
[Interface]
PrivateKey = <base64-workstation-private-key>
Address = 10.200.0.250/24

[Peer]
PublicKey = <base64-node-public-key>
Endpoint = <control-plane-public-ip>:51820
AllowedIPs = 10.200.0.0/24, 10.0.1.0/24
PersistentKeepalive = 25
```

--------------------------------

### Configure Firewall for Production Environment

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/best-practices.md

For production, manually specify source IP ranges using `firewall_use_current_ip = false`. This provides stable and predictable firewall rules.

```hcl
firewall_use_current_ip = false

firewall_kube_api_source = [
  "203.0.113.10/32",      # Your office IP
  "198.51.100.0/24",      # VPN network
]

firewall_talos_api_source = [
  "203.0.113.10/32",      # Your office IP
  "198.51.100.0/24",      # VPN network
]
```

--------------------------------

### Pattern B: Share Network Between Cluster and VPN (BYO Network)

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/README.md

This pattern demonstrates creating a shared Hetzner network and then passing its ID and subnet to both the cluster and VPN gateway modules. This approach is useful when you manage the network independently.

```hcl
# Create the shared network once
resource "hcloud_network" "shared" {
  name     = "shared-net"
  ip_range = "10.0.0.0/16"
}

resource "hcloud_network_subnet" "shared" {
  network_id   = hcloud_network.shared.id
  type         = "cloud"
  network_zone = "eu-central"
  ip_range     = "10.0.1.0/24"
}

# Pass it to the cluster module
module "cluster" {
  source  = "hcloud-talos/talos/hcloud"
  version = "<latest-version>"

  hcloud_token            = "your-hcloud-token"
  firewall_use_current_ip = true
  cluster_name            = "vpn-cluster"
  location_name           = "fsn1"

  # BYO network: module uses this instead of creating a new one
  network_id       = hcloud_network.shared.id
  node_ipv4_cidr   = "10.0.1.0/24" # must match the existing subnet

  control_plane_nodes = [
    { id = 1, type = "cax11" }
  ]
}

# VPN gateway attached to the same network
module "vpn_gateway" {
  source = "./vpn-gateway"

  hcloud_network_id = hcloud_network.shared.id
  node_subnet_cidr  = "10.0.1.0/24"
}
```

--------------------------------

### Manual Etcd Backup and Restore

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/best-practices.md

Talos automatically manages Etcd backups. For manual backups, use `talosctl etcd snapshot`. To restore from a backup after a cluster failure, use `talosctl etcd restore`.

```bash
talosctl -n <control-plane-ip> etcd snapshot <output-file>

# Restore from backup (after full cluster failure)
talosctl -n <control-plane-ip> etcd restore <backup-file>
```

--------------------------------

### Export kubeconfig to File

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/outputs.md

Export the Kubernetes API client configuration to a file and set appropriate permissions. This is required for using kubectl to interact with the cluster.

```bash
terraform output --raw kubeconfig > ~/.kube/config
chmod 600 ~/.kube/config
```

--------------------------------

### Run Quality Checks

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/CONTRIBUTING.md

Execute Terraform formatting, initialization, validation, and all pre-commit hooks to ensure code quality and adherence to project standards.

```bash
terraform fmt -recursive
terraform init
terraform validate
pre-commit run --all-files
```

--------------------------------

### Enable KubeSpan Feature

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/configuration.md

Activate Talos KubeSpan for peer-to-peer node connectivity. Note that this may impact cluster readiness in certain configurations.

```hcl
enable_kube_span = false
```

--------------------------------

### Terraform Testing and Quality Commands

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/CLAUDE.md

Commands for checking Terraform formatting, initialization, validation, and running pre-commit hooks for quality assurance.

```bash
terraform fmt -recursive -check -diff
terraform init && terraform validate
pre-commit run --all-files
```

--------------------------------

### Configure Container Registries

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/configuration.md

Set up container registry mirrors and authentication. Supports defining endpoints for mirrors and credentials for specific registries.

```hcl
registries = {
  mirrors = {
    "docker.io" = {
      endpoints = ["http://registry-mirror:5000", "https://registry-1.docker.io"]
    }
  }
  config = {
    "my-registry.example.com" = {
      auth = {
        username = "myuser"
        password = "mypass"
      }
    }
  }
}
```

--------------------------------

### Configure Firewall for Development Environment

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/best-practices.md

Use `firewall_use_current_ip = true` for development environments. This automatically configures the firewall based on your current IP address, but changes if your IP does.

```hcl
firewall_use_current_ip = true
```

--------------------------------

### Export Cluster Configurations

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/README.md

Export the kubeconfig and talosconfig files to your local machine for kubectl and talosctl access. Ensure correct file permissions are set.

```bash
terraform output --raw kubeconfig > ~/.kube/config
terraform output --raw talosconfig > ~/.talos/config
chmod 600 ~/.kube/config ~/.talos/config
```

--------------------------------

### Configure Extra Sysctl Settings

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/configuration.md

Set additional sysctl parameters on nodes. Each key-value pair becomes a sysctl setting.

```hcl
sysctls_extra_args = {
  "net.core.rmem_default" = "26214400"
  "net.core.wmem_default" = "26214400"
}
```

--------------------------------

### Minimal Development Cluster Testing Commands

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/examples-and-patterns.md

Commands to apply the Terraform configuration, export cluster configurations, and test the cluster's connectivity and version.

```bash
# Apply
terraform apply

# Export configs
terraform output --raw kubeconfig > ~/.kube/config
terraform output --raw talosconfig > ~/.talos/config
chmod 600 ~/.kube/config ~/.talos/config

# Test cluster
kubectl get nodes
talosctl -n $(terraform output -raw public_ipv4_list | jq -r '.[0]') version
```

--------------------------------

### Backup Kubeconfig and Talosconfig

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/best-practices.md

Securely back up your cluster credentials (kubeconfig and talosconfig) to prevent data loss. Store these backups safely and ensure they have restricted file permissions.

```bash
# Store safely (not in Git)
terraform output --raw kubeconfig > ~/backups/kubeconfig-prod
terraform output --raw talosconfig > ~/backups/talosconfig-prod
chmod 600 ~/backups/talos*
```

--------------------------------

### Deploy Cluster with External Load Balancer and DNS

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/examples-and-patterns.md

Set up a production-ready cluster with an external TCP load balancer and DNS integration. This configuration directs traffic to the control plane nodes via a load balancer's IP address, using a specified hostname for access. Ensure your TCP load balancer is configured to forward traffic to the control plane nodes on port 6443.

```hcl
# Assume you have a TCP load balancer configured elsewhere
# Load balancer points to control plane nodes on port 6443

module "talos" {
  source  = "hcloud-talos/talos/hcloud"
  version = "~> 1.0"

  hcloud_token = var.hcloud_token
  
  talos_version      = "v1.12.2"
  kubernetes_version = "1.35.0"
  
  cluster_name            = "lb-cluster"
  cluster_api_host        = "kube.example.com"  # Points to LB IP
  cluster_api_host_private = "kube.internal"     # Points to alias IP
  
  location_name = "fsn1"
  
  firewall_use_current_ip = true
  
  # Use LB hostname in kubeconfig
  kubeconfig_endpoint_mode   = "public_endpoint"
  talosconfig_endpoints_mode = "public_ip"  # Talosctl uses direct IPs
  
  control_plane_nodes = [
    { id = 1, type = "cx33" },
    { id = 2, type = "cx33" },
    { id = 3, type = "cx33" }
  ]
  
  worker_nodes = [
    { id = 1, type = "cx43" },
    { id = 2, type = "cx43" }
  ]
  
  deploy_cilium     = true
  deploy_hcloud_ccm = true
}
```

--------------------------------

### Resource Prefixing Configuration

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/configuration.md

Enable or disable prefixing all Hetzner Cloud resources with the cluster name for easier identification.

```hcl
cluster_prefix = true
```

--------------------------------

### Set Hetzner Cloud ISO ID for ARM64

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/configuration.md

Specify the Hetzner Cloud ISO ID for ARM64 architecture to mount during server boot. Deprecated in favor of custom images.

```hcl
talos_iso_id_arm = "122629"
```

--------------------------------

### Write talos_client_configuration to a local file

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/outputs.md

Use the `local_file` resource to write the structured Talos client configuration to a local file. This is useful for programmatic access or debugging.

```hcl
resource "local_file" "talosconfig" {
  filename   = "${path.module}/talosconfig"
  content    = module.talos.talos_client_configuration.talos_config
  sensitive  = true
}
```

--------------------------------

### Deploy Talos Cluster with Tailscale VPN

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/examples-and-patterns.md

Configures a Talos cluster with Tailscale enabled for secure, encrypted networking. Requires a Tailscale auth key generated from the Tailscale admin panel.

```hcl
module "talos" {
  source  = "hcloud-talos/talos/hcloud"
  version = "~> 1.0"

  hcloud_token = var.hcloud_token
  
  talos_version      = "v1.12.2"
  kubernetes_version = "1.35.0"
  
  cluster_name  = "tailscale-cluster"
  location_name = "fsn1"
  
  firewall_use_current_ip = true
  
  control_plane_nodes = [
    { id = 1, type = "cx33" },
    { id = 2, type = "cx33" },
    { id = 3, type = "cx33" }
  ]
  
  worker_nodes = [
    { id = 1, type = "cx43" },
    { id = 2, type = "cx43" }
  ]
  
  # Enable Tailscale
  tailscale = {
    enabled  = true
    auth_key = var.tailscale_auth_key  # Generated from Tailscale admin panel
  }
  
  # Cilium LB acceleration compatibility
  # (Tailscale + eBPF requires "best-effort" mode)
  
  deploy_cilium     = true
  deploy_hcloud_ccm = true
}

output "cluster_ips" {
  value = {
    public_ips = module.talos.public_ipv4_list
    # Nodes are also accessible via Tailscale IPs from your Tailscale network
  }
}
```

--------------------------------

### Access Talos Cluster Nodes via Tailscale

Source: https://github.com/hcloud-talos/terraform-hcloud-talos/blob/main/_autodocs/examples-and-patterns.md

Demonstrates how to access cluster nodes using SSH and kubectl after they have booted with Tailscale enabled. Nodes are accessible via their Tailscale IPs.

```bash
# Once nodes boot with Tailscale, you can access them via Tailscale IPs:
ssh user@<tailscale-ip>
kubectl --kubeconfig kubeconfig get nodes
```