terraform-hcloud-kubernetes: a declarative Talos cluster on Hetzner Cloud

Talos is the reason the cluster can be declarative

The module's pitch is that a Hetzner Cloud Kubernetes cluster can be fully declarative and managed, and the enabling choice is Talos, described as a secure, immutable and minimal operating system built specifically for Kubernetes, with a streamlined architecture of only a handful of binaries and shared libraries, just enough to run containerd and a small set of system services. That is the whole design argument. A conventional node OS brings a package manager, a service manager and a long list of things that can drift, and every one of them is something a configuration management tool has to own. Talos replaces that surface, and the README frames the result as production-grade configuration and lifecycle management with all components set up for high availability. The audience is therefore infrastructure engineers who already live in Terraform and who want their cluster to be reproducible from code rather than assembled by hand and then documented after the fact.

The bundled components are the Hetzner and Talos specific ones

The component list is short enough to read in one pass and tells you what the module saves you from wiring up. Talos Cloud Controller Manager automatically approves kubelet server certificate signing requests for Talos nodes, which matters because Talos nodes do not behave like ordinary kubelets in that respect. Talos Backup automates etcd snapshots and S3 storage for backup in Talos based clusters. Hcloud Cloud Controller Manager handles the Hetzner side of the integration, updating node data, controlling private network traffic and setting up load balancers. The Hcloud Container Storage Interface provides persistent storage using Hetzner Cloud Volumes with encryption and dynamic provisioning. Longhorn supplies distributed block storage with high availability, snapshots and automatic replica rebuilding, and Cilium appears in the component list as the container networking piece. Each of these is upstream software, and the module's value is in preconfiguring them for Hetzner rather than inventing them.

Node images are built with Packer for two architectures

Based on the repository layout, images are produced by a packer directory alongside an image.tf file, and the README states that the module supports deployment on both AMD64 and ARM64 instances with automated image builds. That matters on Hetzner specifically, where the two architectures are not interchangeable products but different hardware lines with different prices and different CPU features, and where a cluster spanning both is common. The Talos configuration is split into separate files per role, with talos_config_base.tf, talos_config_control_plane.tf, talos_config_worker.tf and a dedicated talos_config_bare_metal.tf, plus a talos_config_cluster_autoscaler.tf. Splitting the machine configuration by role is what makes a single module able to produce control plane and worker nodes from the same code base, and the presence of a separate bare metal configuration file shows that the bare metal path is not a variation handled with a flag.

Networking is a private cloud network with firewalls and dual-stack load balancers

The network story is the part where a Hetzner cluster usually goes wrong by default, and the module addresses it directly. The README promises an isolated network that keeps all internal cluster traffic inside a private Hetzner Cloud Network, a security-first architecture with perimeter firewalls, and encryption for data in transit and at rest. Load balancers are described as natively dual-stack, providing IPv4 and IPv6 connectivity with PROXY Protocol support, which is what allows the source address of a real client to survive the hop through the load balancer. In the file listing this appears as network.tf, firewall.tf, load_balancer.tf and floating_ip.tf, with placement_group.tf and vswitch.tf alongside, and rdns.tf for reverse DNS. The floating IP and rDNS entries indicate that the module treats ingress addressing as part of the cluster definition rather than something you configure later by hand.

Optional integrations decide how much you get out of the box

Several capabilities are presented as optional rather than default, which is the sensible design for a module that has to work on clusters of very different sizes. The README lists optional Gateway API, Cert Manager and Longhorn integrations under a quick start heading, described as faster app deployment. The file listing shows how those map onto the code: cert_manager.tf and cert_manager_webhook_hetzner.tf cover certificate management including the webhook's own Hetzner specifics, longhorn.tf covers the storage layer, cilium.tf the networking, cluster_autoscaler.tf and metrics_server.tf the autoscaling and metrics side, and oidc.tf and rbac.tf cover authentication and authorisation. The naming of the cluster autoscaler file under talos_config suggests the autoscaler is configured through the Talos machine configuration rather than as a separate deployment, and the presence of a dedicated file for it says the integration is not a token gesture.

Autoscaling covers both nodes and pods, and the cluster layout is a nodepool

The README lists autoscaling of both nodes and pods as a feature, alongside a separate mention of a cluster autoscaler configuration file and an autoscaler template in the templates directory. Node and pod autoscaling are two different mechanisms that are often conflated: one adds or removes machines, the other adds or removes workload replicas inside existing nodes, and a cluster that wants one without the other needs the infrastructure API or the metrics pipeline to behave. Having both in the module means the scaling story is not left to the workload owner. The overall cluster shape comes from nodepool.tf and server.tf, with ssh_key.tf and client.tf handling access, so a change of node count or a new pool is a Terraform change rather than a console click, which is the property the module is really selling.

Getting the module: registry path, provider and API token

The module is not cloned and run from source, it is consumed as a registry module, and the README gives the registry path directly: the module lives at hcloud-k8s/kubernetes/hcloud on the Terraform Registry, and an OpenTofu registry entry exists as well, so the same module block resolves under either tool. That distinction matters for teams that have standardised on OpenTofu and no longer want a Terraform binary in CI. The README does not walk through a first apply, and it does not list the required provider versions or the variable names, so the practical first step for an adopter is to read variables.tf in the repository and the module page on the registry, where the inputs are documented. Whatever the tool, the cloud side is Hetzner: a project, a network, and an API token with permission to create servers, firewalls, load balancers, volumes and networks, because the module creates all of those as declared resources rather than attaching to anything you made by hand.

MIT licensed, released several times in October 2026

The module is MIT licensed with the licence file in the repository root, and it is published in two registries: the Terraform Registry under hcloud-k8s/kubernetes/hcloud, which is also listed as the project homepage, and an OpenTofu registry entry, visible in the README badge row. Publishing to both matters for teams that have moved to OpenTofu and do not want to keep a Terraform binary around for one module. The release history shows a steady 6.x line, with 6.1.0 on 2026-10-10, 6.2.0 on 2026-10-15 and 6.3.0 on 2026-10-19, and the last push to the repository was on 2026-10-19 as well. Frequent minor releases on a fast-moving dependency set are the norm for this kind of module, so the upgrade cadence is part of the operational cost, and pinning a version rather than tracking the branch is the sane default.

Editorial conclusion

terraform-hcloud-kubernetes fits a team that wants a Kubernetes cluster on Hetzner Cloud described entirely in Terraform, with Talos as the immutable node OS and the Hetzner-specific controllers wired in for them. It does not fit someone who wants a managed control plane, or a team that needs a component the module does not carry and would rather maintain it themselves. Before adopting it, read the variables file to see what it exposes, confirm your Hetzner project and network layout match the module's assumptions, and check the pinned versions of the bundled components against the Kubernetes version you intend to run.

Frequently asked questions

Official sources

1. hcloud-k8s/terraform-hcloud-kubernetes on GitHub
2. License: MIT
3. Project website
4. README
5. Releases