terraform-hcloud-kube-hetzner

To access your cluster, retrieve the kubeconfig via Terraform outputs.

To view the kubeconfig:

terraform output kubeconfig

To use it with kubectl:

# Set as default
export KUBECONFIG=/<path-to>/clustername_kubeconfig.yaml

# Or use directly
kubectl --kubeconfig clustername_kubeconfig.yaml get nodes

If create_kubeconfig = false was set in your configuration, generate it manually using:

terraform output --raw kubeconfig > clustername_kubeconfig.yaml

terraform output kubeconfig
terraform output -json kubeconfig | jq

To use encrypted HCloud volumes, create a Kubernetes secret containing the passphrase and then define a StorageClass that references this secret via the csi.storage.k8s.io/node-publish-secret-name parameter.

# 1. Create the secret
apiVersion: v1
kind: Secret
metadata:
  name: encryption-secret
  namespace: kube-system
stringData:
  encryption-passphrase: foobar
---
# 2. Create the storage class
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: hcloud-volumes-encrypted
provisioner: csi.hetzner.cloud
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
parameters:
  csi.storage.k8s.io/node-publish-secret-name: encryption-secret
  csi.storage.k8s.io/node-publish-secret-namespace: kube-system

Use the following command sequence to validate the Terraform/OpenTofu configuration and custom validation scripts before applying changes:

terraform fmt -recursive
terraform-docs markdown . > docs/terraform.md
terraform init -backend=false
terraform validate
tofu init -backend=false
tofu validate
uv run scripts/validate_tailscale_large_scale_examples.py
uv run scripts/validate_v3_final_polish_examples.py
git diff --check

Choose a topology based on your requirements:

Once your project folder is initialized and kube.tf is customized, use Terraform or OpenTofu to deploy the infrastructure.

Warning: Once Terraform manages your cluster, avoid making manual changes in the Hetzner Cloud UI. Use the hcloud CLI for inspection.

### Using Terraform
```sh
cd <your-project-folder>
terraform init --upgrade
terraform validate
terraform plan
terraform apply -auto-approve

Using OpenTofu

tofu init --upgrade
tofu validate
tofu plan
tofu apply -auto-approve

To ensure a safe in-place upgrade, use this command to check if the Terraform plan proposes destroying any critical Hetzner Cloud resources.

Contract: If the command produces no output, the protected-infrastructure gate passed. If it produces any output, stop immediately and investigate the proposed deletions before applying.

terraform show -json v3-upgrade.tfplan \
  | jq -r '
      .resource_changes[]?\
      | select(.type as $type | [
          "hcloud_server",
          "hcloud_network",
          "hcloud_network_subnet",
          "hcloud_load_balancer",
          "hcloud_volume",
          "hcloud_primary_ip",
          "hcloud_placement_group",
          "hcloud_firewall"
        ] | index($type))\
      | select(.change.actions | index("delete"))\
      | "\(.address): \(.type) \(.change.actions | join(","))"
    '

Autoscaling is enabled via the autoscaler_nodepools variable and is powered by the Kubernetes Cluster Autoscaler.

Important Considerations:

• Snapshots: Autoscaled nodes use a snapshot from the initial control plane. Ensure disk sizes match.
• Longhorn Storage: Keep Longhorn on static agent nodepools. Autoscaled Longhorn volumes require a write-capable Hetzner token in node user-data and can leave detached volumes behind during scale-down.
• Local Storage: The autoscaler will not scale down nodes running pods with local storage unless configured. To allow eviction of such pods, add --skip-nodes-with-local-storage=false to cluster_autoscaler_extra_args or annotate pods with cluster-autoscaler.kubernetes.io/safe-to-evict: "true".

To enable automated, scheduled etcd backups to S3 in your kube.tf configuration, follow these steps:

1. Populate the etcd_s3_backup configuration in your kube.tf file.
2. Export the cluster_token as a Terraform output so it can be retrieved later:

output "cluster_token" {
  value     = module.kube-hetzner.cluster_token
  sensitive = true
}

3. Verify you can access the token using the command terraform output cluster_token.

Hetzner Placement Groups ensure servers are located on different physical hosts to improve fault tolerance.

• Limits: Each placement group supports a maximum of 10 servers. The project limit is 50 groups.
• Auto-sharding: If enable_placement_groups is true and you do not specify a placement_group, the module automatically shards nodepools every 10 servers.
• Manual Assignment: To group specific nodes together, provide the same placement_group name to multiple nodepool maps.

If you want to contribute a new rule to the kube-hetzner repository, ensure your proposal includes the following evidence:

• The exact AVC denial lines.
• The name and version of the workload.
• The Kubernetes distribution used (k3s or rke2).
• The OS image used (leapmicro or microos).
• Confirmation of whether a targeted udica policy successfully resolved the issue.

Rules without real AVC evidence will not be accepted into the main policy.