hetzner-k3s: Kubernetes clusters on Hetzner Cloud without Terraform

What hetzner-k3s removes from the cluster-building job

Building a Kubernetes cluster on a cloud provider usually means assembling several tools. Terraform describes the servers, a configuration management tool installs the runtime, and something else wires up storage and load balancers. hetzner-k3s collapses that into a single CLI written in Crystal. The README states it needs no Terraform, Packer, Ansible or existing Kubernetes cluster, and that the whole cluster is described by one human-readable YAML file you can keep in version control.

The intended user is a small team or a solo operator who wants Kubernetes on Hetzner Cloud without learning a provisioning stack first. The README is explicit that the Hetzner API token never leaves your machine, which distinguishes it from managed services where a third party holds credentials. The project is MIT licensed and maintained by one developer, who asks for sponsorship in the README. That single-maintainer fact matters more than any feature list: it tells you where the upgrade path and the bug backlog will come from.

The mechanism: one binary, the Hetzner API, and cloud-init

There is no management cluster and no controller running on your side. The CLI talks to the Hetzner Cloud API directly, creates the servers you declared, and bootstraps them. According to the README, running `hetzner-k3s create` produces k3s plus four integrated components: the Hetzner Cloud Controller Manager for load balancer provisioning, the Hetzner CSI driver for persistent volumes on block storage, the System Upgrade Controller for k3s upgrades, and the Cluster Autoscaler for node scaling. Traefik, ServiceLB and metrics-server are listed as optional add-ons rather than defaults.

That component set is the interesting design decision. The cloud controller manager and CSI driver are what make a self-managed cluster behave like a provider-integrated one: without them, a Service of type LoadBalancer and a PersistentVolumeClaim would both sit pending. The System Upgrade Controller is the opposite kind of choice. It moves k3s upgrades into the cluster, which means an upgrade is a change you schedule rather than a command the CLI runs for you. The README does not document rollback for a failed upgrade, so treat that path as unverified until you read the installation guide.

Networking is private by default in the sense that the README says everything is integrated with Hetzner's private networking and firewall. The cluster config also carries SSH settings, so server access is part of the same file rather than a separate concern.

Installing the CLI and creating a first cluster

On macOS or Linux, the README gives a Homebrew tap. The formula name uses an underscore, not a hyphen, which is easy to mistype.

brew install vitobotta/tap/hetzner_k3s

On Linux amd64 the README shows a direct download from the v2.6.0 release, a chmod, and a move into /usr/local/bin. The installation guide linked from the README covers the other platforms.

wget https://github.com/vitobotta/hetzner-k3s/releases/download/v2.6.0/hetzner-k3s-linux-amd64
chmod +x hetzner-k3s-linux-amd64
sudo mv hetzner-k3s-linux-amd64 /usr/local/bin/hetzner-k3s

Configuration is a single file. The README's example is named cluster.yaml and starts with the token, the cluster name, a kubeconfig path and a k3s version, then a networking block with the SSH port, whether to use an agent, and paths to the public and private keys.

hetzner_token: <your-token>
cluster_name: my-cluster
kubeconfig_path: "./kubeconfig"
k3s_version: v1.32.0+k3s1

networking:
  ssh:
    port: 22
    use_agent: false
    public_key_path: "~/.ssh/id_ed25519.pub"
    private_key_path: "~/.ssh/id_ed25519"

Keep the token out of the committed file. The README does not show an environment variable for it, so if you version-control cluster.yaml, the token line is the one to replace before committing. After the create command finishes, the kubeconfig should appear at the path you set, which is what you point kubectl at for the first real workload.

Cluster size, cost, and where the speed claim comes from

The README makes two performance claims: a 3-node HA cluster in 2 to 3 minutes, and a 500-node cluster in under 11 minutes with 3 masters and 497 workers. Those are the maintainer's figures, not independently reproduced here, and the honest reading is that they describe the provisioning step, not the time to a fully warmed cluster running your workloads. The reason the numbers are plausible at all is the absence of a management cluster and of a configuration management pass over every node: there is one binary, an API call per server, and cloud-init on the way up.

The cost table is the more useful part. December 2025 pricing in the README puts a development cluster (one CX23 master, two CX23 workers) at roughly €16 per month, a small production cluster (three CPX22 masters, three CPX32 workers) at about €58, and a large one (three CPX42 masters, fifty CPX32 workers) at around €615. The README says those figures include a load balancer at about €5.50 per month. It also compares the small production case to an equivalent AWS EKS setup at 3 to 5 times the infrastructure cost plus a $0.10 per hour cluster fee, roughly $73 per month.

Treat the comparison as directional. It prices infrastructure and the EKS control plane fee, and says nothing about egress, snapshots, or the engineering time you spend running the cluster yourself. That last item is the real cost of this tool and it does not appear in any table.

Limits, failure modes, and when hetzner-k3s is the wrong choice

The tool is bound to one provider. Every part of the mechanism, the cloud controller manager, the CSI driver, the load balancer provisioning, assumes Hetzner Cloud. If your requirement is a cluster that can move between providers, or that runs the same way on bare metal, this is not the layer to build that on.

You own the control plane. Three masters in the config give you high availability, but there is no vendor behind them. Node failures, etcd health and k3s upgrades are your operational surface. The System Upgrade Controller handles the mechanics of upgrading k3s, and the README does not document a rollback path, so a failed upgrade is a problem you debug rather than a button you press.

The project is maintained by one developer. The README says so directly and asks for sponsorship. That is not a defect, but it is a planning input: release cadence and response time on issues depend on one person, and the last push to the repository was on 2026-08-25.

Finally, there is no managed control plane and no support contract. If your organisation needs an SLA attached to the API server, or needs someone to call at 3am, a managed Kubernetes offering is the correct answer even at several times the infrastructure cost.

hetzner-k3s compared with Terraform and with managed Kubernetes

The most common alternative people reach for is Terraform plus a bootstrap step: hcloud provider resources for servers and networks, then a provisioner or cloud-init to install k3s, then separate Helm installs for the cloud controller manager, the CSI driver and the autoscaler. The difference is where the logic lives. Terraform keeps a state file that describes the infrastructure and can plan changes before applying them; hetzner-k3s keeps no such plan output and instead re-reads your YAML. Terraform gives you drift detection and a diff before anything changes. hetzner-k3s gives you one file and one command, and the README's pitch is that you do not have to learn Terraform to get a cluster.

If your team already runs Terraform for other infrastructure, adding hetzner-k3s means a second, unrelated model of the same servers. That is a real cost, and the README's framing, that there is no Terraform to learn, cuts the other way once Terraform is already in place.

The other alternative is a managed Kubernetes service on Hetzner or elsewhere. The README mentions managed Hetzner services such as Cloudfleet and notes that platform fees scale with cluster size. The trade is straightforward: you pay a platform fee and hand over control plane operations, and in return you get a provider-managed API server and, usually, a support path. hetzner-k3s gives you the lower bill and the direct control, and leaves the operational work with you.

Maintenance, upgrades, and the MIT licence

Upgrades happen at two levels. The k3s version is a field in cluster.yaml, and the System Upgrade Controller installed by the tool is what applies changes to it, according to the README's component table. The CLI itself is a binary you replace: Homebrew handles it on macOS and Linux, or you download a newer release binary over the one in /usr/local/bin. The README does not describe an in-place self-update command, so plan on the package manager or a fresh download.

The repository also ships a docker-compose.yml for development, which builds from Dockerfile.dev, mounts the working directory at /home/app/hetzner-k3s, mounts your SSH directory into the container, and keeps a kube volume at /root/.kube. A commented network_mode: host line notes that connecting to servers over IPv6 from a container requires Docker IPv6 configuration, or host networking on Linux. That file is for working on the tool, not for running clusters.

The licence is MIT, stated in the README and present as LICENSE.txt in the repository root. In practical terms MIT permits commercial use and modification with the copyright notice retained. This is not legal advice; if your organisation has licence review, the file to hand over is LICENSE.txt.

Editorial conclusion

Adopt hetzner-k3s if you want Hetzner Cloud nodes and a k3s control plane you configure yourself from one YAML file, and if you are comfortable owning upgrades and node lifecycle. Do not adopt it if you need a managed control plane, multi-cloud portability, or a support contract behind the cluster. Before you commit, verify the k3s_version value against the releases available at install time, confirm the instance types in your config exist in the region you chose, and read the installation guide for the platform you will run the CLI on.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. vitobotta/hetzner-k3s on GitHub