hetzner-k3s: one Crystal CLI and one YAML file to build k3s clusters on Hetzner Cloud
The easiest and fastest way to create production-ready Kubernetes clusters on Hetzner Cloud
At a glance
- What is it?
- hetzner-k3s creates k3s Kubernetes clusters on Hetzner Cloud from a single cluster.yaml, with no Terraform, Packer, Ansible or management cluster. This piece looks at what the create command installs, which config fields matter, and where the tool stops.
- Who is it for?
- Use it if you already run on Hetzner Cloud and want a k3s cluster from one YAML file without learning Terraform. Skip it if you need a provider other than Hetzner or a project with more than one maintainer.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Crystal, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 22, 2026, and from our analysis. They are not legal advice.
Star history
- vitobotta/hetzner-k3s3,736 ★ · +49
| Repository | 2026-09-24 | 2026-11-22 |
|---|---|---|
| vitobotta/hetzner-k3s | 3.7k | 3.7k |
49 Stars in the last 59 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The token never leaves your machine because there is no control plane in between
hetzner-k3s is a command line tool written in Crystal, licensed MIT, whose default branch is main. It talks to the Hetzner API directly with the token you put in hetzner_token, so the project's pitch is that no Terraform, Packer, Ansible, existing Kubernetes cluster or third-party account is involved. That has a concrete consequence: the token sits in a plain YAML file on whichever machine runs the tool, and protecting that file is your job. The flip side is that nobody else can see your clusters or workloads, and there are no platform fees beyond what Hetzner charges for the servers, load balancer and volumes.
What create puts on the cluster, and what stays optional
Running hetzner-k3s create installs k3s itself, the Hetzner Cloud Controller Manager for automatic load balancer provisioning, the Hetzner CSI Driver for persistent volumes on Hetzner block storage, the System Upgrade Controller for k3s upgrades, and the Cluster Autoscaler for node scaling. These are wired into Hetzner's private networking and firewall. Traefik, ServiceLB and metrics-server are optional add-ons rather than defaults. So if you want to run without Traefik, you leave that add-on out and bring your own ingress. The project describes k3s as a certified Kubernetes distribution that uses less memory and CPU than a full distribution and ships as a single binary.
The sample cluster.yaml spreads masters across three Hetzner locations
The starter file pins k3s_version to v1.32.0+k3s1 and writes the kubeconfig to ./kubeconfig. The masters_pool uses instance type cpx22 with instance_count 3 and lists locations fsn1, hel1 and nbg1, so the control plane spans Falkenstein, Helsinki and Nuremberg. The worker_node_pools entry is named workers, uses cpx32, has three nodes, and sits in a single location, hel1. The consequence of that split is worth noticing: a Helsinki outage takes out every worker in the sample, even though the masters survive. SSH is set to port 22 with use_agent false and an ed25519 key pair under ~/.ssh, so the key paths must exist before you run anything.
The sample allows SSH and API access from the whole internet
Under networking.allowed_networks, both ssh and api contain 0.0.0.0/0. Copy that file unchanged and the Kubernetes API and port 22 on your nodes are reachable from anywhere, with only your keys and certificates standing between the internet and the cluster. The sample is a starting point, not a hardened baseline, so replace those entries with your office or VPN ranges before you create a cluster you intend to keep. The project points to its Creating a Cluster page for a complete example with all available options, which is where tighter settings would be found.
Homebrew or a pinned release binary
There are two quick install routes shown. On macOS or Linux, Homebrew installs from the vitobotta tap:
brew install vitobotta/tap/hetzner_k3sOn Linux amd64 you can fetch the release binary directly:
wget https://github.com/vitobotta/hetzner-k3s/releases/download/v2.7.0/hetzner-k3s-linux-amd64
chmod +x hetzner-k3s-linux-amd64
sudo mv hetzner-k3s-linux-amd64 /usr/local/bin/hetzner-k3sThe wget URL is pinned to v2.7.0, so a copy-pasted command keeps installing that version even after newer tags appear. The other platforms are covered in the separate Installation Guide. Once the file is ready, the cluster comes up with hetzner-k3s create --config cluster.yaml, after which the kubeconfig is saved automatically and you check the nodes like this:
export KUBECONFIG=./kubeconfig
kubectl get nodesThe speed and cost figures are the author's own claims
The README says a 3-node HA cluster takes 2-3 minutes and that a cluster with 3 masters and 497 workers came up in under 11 minutes, adding that this is possibly a world record. Those are the author's numbers, so treat them as a ceiling for a good day rather than a promise. The cost table uses December 2025 pricing: about 16 euros a month for 1 master and 2 workers on CX23, about 58 for 3 CPX22 masters and 3 CPX32 workers, about 135 with 10 workers, and about 615 for 3 CPX42 masters with 50 CPX32 workers, all including a load balancer at roughly 5.50 euros. Hetzner prices move, so recompute before budgeting. The claim of up to 80 percent lower cost than AWS, Google Cloud and Azure is likewise the project's own comparison.
One maintainer and one cloud provider
The README states that hetzner-k3s is maintained by a single developer and asks users to sponsor it. The repository is not archived. The latest push was on 2026-10-30, and releases v2.5.0 on 2026-05-07, v2.6.0 on 2026-06-24 and v2.7.0 on 2026-10-25 show steady movement. For you, a single maintainer means fixes depend on one person's time. The tool only targets Hetzner Cloud, so moving to another provider means changing tools, and the Hetzner-specific components such as the CSI driver and Cloud Controller Manager do not carry over. The repository also includes a docker-compose.yml that mounts your ~/.ssh and the Docker socket into a development container, which suits contributors rather than people just running clusters.
Editorial conclusion
Use it if you already run on Hetzner Cloud and want a k3s cluster from one YAML file without learning Terraform. Skip it if you need a provider other than Hetzner or a project with more than one maintainer. Before the first create, tighten the 0.0.0.0/0 network rules from the sample file and check the cost table against current Hetzner prices, since it uses December 2025 figures.
Frequently asked questions
Can I use K3s without Traefik in hetzner-k3s?
Yes. Traefik, ServiceLB and metrics-server are optional add-ons in hetzner-k3s rather than defaults, so you can leave Traefik out.
Is K3s real Kubernetes, as used by hetzner-k3s?
The project describes k3s from Rancher as a certified Kubernetes distribution optimized for resource efficiency, shipped as a single binary.
Why is Hetzner cheap compared with AWS for a hetzner-k3s cluster?
The project claims up to 80% lower costs than AWS, Google Cloud and Azure, with traffic, IPv4/IPv6, DDoS protection and firewalls included in the price. It gives figures, not a reason.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/vitobotta-hetzner-k3s)Star history chart for your README
[](https://hysenlabs.com/projects/vitobotta-hetzner-k3s)Was this useful?