GitHub release (latest SemVer) GitHub Release Date GitHub last commit GitHub issues GitHub pull requests GitHub GitHub Discussions GitHub top language

GitHub forks GitHub Repo stars

 _          _                            _    _____
| |__   ___| |_ _____ __   ___ _ __     | | _|___ / ___
| '_ \ / _ \ __|_  / '_ \ / _ \ '__|____| |/ / |_ \/ __|
| | | |  __/ |_ / /| | | |  __/ | |_____|   < ___) \__ \
|_| |_|\___|\__/___|_| |_|\___|_|       |_|\_\____/|___/

The easiest and fastest way to create production-ready Kubernetes clusters on Hetzner Cloud

hetzner-k3s logo

hetzner-k3s.com

Table of Contents

Why hetzner-k3s?

hetzner-k3s is a CLI tool that creates production-ready Kubernetes clusters on Hetzner Cloud in minutes, not hours. No Terraform to learn, no management cluster required, no third-party access to your credentials.

Speed That Sets Records

Simplicity Without Compromise

Complete Control, Zero Lock-in

How It Works

How hetzner-k3s works

No Terraform. No Packer. No Ansible. No management cluster. No third-party account. Your API token never leaves your machine.

Why Hetzner Cloud + k3s?

Hetzner Cloud: Exceptional Value

Hetzner Cloud offers the best performance-to-cost ratio in the industry:

k3s: Lightweight Kubernetes

k3s by Rancher is a certified Kubernetes distribution optimized for resource efficiency:

Sample Monthly Costs

Real infrastructure costs for common cluster configurations (December 2025 pricing):

| Cluster Type | Configuration | Monthly Cost | |--------------|---------------|--------------| | Development | 1 master (CX23), 2 workers (CX23) | ~€16/month | | Small Production | 3 masters (CPX22), 3 workers (CPX32) | ~€58/month | | Medium Production | 3 masters (CPX22), 10 workers (CPX32) | ~€135/month | | Large Production | 3 masters (CPX42), 50 workers (CPX32) | ~€615/month |

Includes load balancer (~€5.50/month). No management fees, no per-user fees—just infrastructure.

Compare to managed alternatives:

What Gets Installed

When you run hetzner-k3s create, you get a complete, production-ready cluster:

| Component | Purpose | |-----------|---------| | k3s | Lightweight Kubernetes distribution | | Hetzner Cloud Controller Manager | Automatic load balancer provisioning | | Hetzner CSI Driver | Persistent volumes via Hetzner block storage | | System Upgrade Controller | Zero-downtime k3s upgrades | | Cluster Autoscaler | Automatic node scaling based on demand |

All integrated with Hetzner's private networking and firewall. Traefik, ServiceLB, and metrics-server are available as optional add-ons.

Quick Start

1. Install hetzner-k3s

Homebrew (macOS/Linux):

brew install vitobotta/tap/hetzner_k3s

Linux binary (amd64):

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

See Installation Guide for all platforms.

2. Create a Configuration File

Create cluster.yaml:

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"
  allowed_networks:
    ssh:
      - 0.0.0.0/0
    api:
      - 0.0.0.0/0

masters_pool:
  instance_type: cpx22
  instance_count: 3
  locations:
    - fsn1
    - hel1
    - nbg1

worker_node_pools:
- name: workers
  instance_type: cpx32
  instance_count: 3
  location: hel1

See Creating a Cluster for a complete configuration example with all available options.

3. Create Your Cluster

hetzner-k3s create --config cluster.yaml

In 2-3 minutes, your cluster is ready. The kubeconfig is saved automatically.

export KUBECONFIG=./kubeconfig
kubectl get nodes

Who Uses hetzner-k3s?

Join an active community with 3,100+ GitHub stars and regular contributions.

How It Compares

| Factor | hetzner-k3s | Managed Services | Terraform-based | |--------|-------------|------------------|-----------------| | Setup time | 2-3 minutes | 5-10 minutes | 15-30+ minutes | | Dependencies | CLI tool only | Third-party account* | Terraform, Packer, HCL knowledge | | Data privacy | Full control | Third-party access | Full control | | Monthly cost | Infrastructure only | Infrastructure + platform fees | Infrastructure only | | Credential exposure | None | API tokens to third party | None | | Learning curve | Low | Low | Medium-High |

*Managed services (Cloudfleet, Edka, etc.) require signing up for their platform in addition to Hetzner Cloud.

For a detailed comparison, see Why hetzner-k3s Stands Out.

Key Features

High Availability

Deploy masters and worker pools across multiple locations for regional resilience.

Autoscaling

Define min/max instances per node pool. The Cluster Autoscaler handles the rest.

worker_node_pools:
- name: autoscaled
  instance_type: cpx32
  location: fsn1
  autoscaling:
    enabled: true
    min_instances: 1
    max_instances: 10

Multiple Node Pools

Mix instance types and locations for different workloads. Hetzner offers x86 and ARM instances at various performance levels—including cost-effective ARM instances (CAX) ideal for budget-friendly clusters.

Private Networking

Cluster communication over Hetzner's private network by default.

CNI Options

Choose Flannel (simple) or Cilium (advanced networking features).

Large Cluster Support

Tested with 500 nodes and designed to scale beyond. Clusters over 100 nodes require some configuration changes (see Recommendations).

Documentation

Full documentation: vitobotta.github.io/hetzner-k3s

Who am I?

I'm Vito Botta, Lead Platform Architect at Brella, an event management platform based in Finland. I handle infrastructure, coding, and support for the development team.

I also spend time as a bug bounty hunter, finding and responsibly reporting security vulnerabilities.

Connect with me at vitobotta.com. I'm available for consultancies around hetzner-k3s and Kubernetes on Hetzner.

Sponsors

Your support helps keep this project actively maintained. Consider sponsoring development.

Platinum Sponsors

Alamos GmbH

A special thank you to Alamos GmbH for sponsoring the development of key features!

Backers

Thanks to @deubert-it, @jonasbadstuebner, @ricristian, @QuentinFAIDIDE for their support!

Contributing

Contributions are welcome! See Contributing and Support for guidelines.

Code of Conduct

Everyone interacting in this project is expected to follow the code of conduct.

License

Open source under the MIT License.

Star History

Stargazers over time