{"id":13573831,"url":"https://github.com/vitobotta/hetzner-k3s","last_synced_at":"2026-02-28T20:05:24.914Z","repository":{"id":39652103,"uuid":"393666948","full_name":"vitobotta/hetzner-k3s","owner":"vitobotta","description":"The easiest and fastest way to create and manage Kubernetes clusters in Hetzner Cloud using the lightweight distribution k3s by Rancher.","archived":false,"fork":false,"pushed_at":"2025-04-23T15:07:42.000Z","size":13189,"stargazers_count":2390,"open_issues_count":24,"forks_count":165,"subscribers_count":37,"default_branch":"main","last_synced_at":"2025-05-13T00:12:24.550Z","etag":null,"topics":["crystal","crystal-lang","crystal-language","devops","docker","hetzner","hetzner-api","hetzner-cloud","k3s","k8s","kubernetes"],"latest_commit_sha":null,"homepage":"","language":"Crystal","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vitobotta.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/Contributing_and_support.md","funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["vitobotta"]}},"created_at":"2021-08-07T11:39:12.000Z","updated_at":"2025-05-12T19:57:12.000Z","dependencies_parsed_at":"2023-02-18T18:45:41.542Z","dependency_job_id":"cfe9efba-1fd4-487d-8748-b5ff7c1b2790","html_url":"https://github.com/vitobotta/hetzner-k3s","commit_stats":{"total_commits":832,"total_committers":33,"mean_commits":25.21212121212121,"dds":"0.10096153846153844","last_synced_commit":"60b862b3105d6a7362f5754ee83b5f91a2014984"},"previous_names":[],"tags_count":134,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitobotta%2Fhetzner-k3s","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitobotta%2Fhetzner-k3s/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitobotta%2Fhetzner-k3s/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitobotta%2Fhetzner-k3s/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vitobotta","download_url":"https://codeload.github.com/vitobotta/hetzner-k3s/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253843219,"owners_count":21972874,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crystal","crystal-lang","crystal-language","devops","docker","hetzner","hetzner-api","hetzner-cloud","k3s","k8s","kubernetes"],"created_at":"2024-08-01T15:00:41.874Z","updated_at":"2026-02-28T20:05:24.897Z","avatar_url":"https://github.com/vitobotta.png","language":"Crystal","funding_links":["https://github.com/sponsors/vitobotta"],"categories":["Crystal","Ruby","CLI Utils","Tools"],"sub_categories":["Rust"],"readme":"![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/vitobotta/hetzner-k3s)\n![GitHub Release Date](https://img.shields.io/github/release-date/vitobotta/hetzner-k3s)\n![GitHub last commit](https://img.shields.io/github/last-commit/vitobotta/hetzner-k3s)\n![GitHub issues](https://img.shields.io/github/issues-raw/vitobotta/hetzner-k3s)\n![GitHub pull requests](https://img.shields.io/github/issues-pr-raw/vitobotta/hetzner-k3s)\n![GitHub](https://img.shields.io/github/license/vitobotta/hetzner-k3s)\n![GitHub Discussions](https://img.shields.io/github/discussions/vitobotta/hetzner-k3s)\n![GitHub top language](https://img.shields.io/github/languages/top/vitobotta/hetzner-k3s)\n\n![GitHub forks](https://img.shields.io/github/forks/vitobotta/hetzner-k3s?style=social)\n![GitHub Repo stars](https://img.shields.io/github/stars/vitobotta/hetzner-k3s?style=social)\n\n---\n\n\u003e **❤️ Support This Project**\n\u003e\n\u003e hetzner-k3s is maintained by a single developer. If it saves you time or money, please consider sponsoring its continued development.\n\u003e\n\u003e **[Become a sponsor →](https://github.com/sponsors/vitobotta)**\n\n---\n\n# The easiest and fastest way to create production-ready Kubernetes clusters on Hetzner Cloud\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo-v2.png\" alt=\"hetzner-k3s logo\" width=\"200\" height=\"200\" style=\"margin-left: auto;\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://hetzner-k3s.com/\"\u003e\u003cstrong\u003ehetzner-k3s.com\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Table of Contents\n\n- [Why hetzner-k3s?](#why-hetzner-k3s)\n  - [How It Works](#how-it-works)\n- [Why Hetzner Cloud + k3s?](#why-hetzner-cloud--k3s)\n  - [Sample Monthly Costs](#sample-monthly-costs)\n- [What Gets Installed](#what-gets-installed)\n- [Quick Start](#quick-start)\n- [Who Uses hetzner-k3s?](#who-uses-hetzner-k3s)\n- [How It Compares](#how-it-compares)\n- [Key Features](#key-features)\n- [Documentation](#documentation)\n- [Who am I?](#who-am-i)\n- [Sponsors](#sponsors)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Why hetzner-k3s?\n\n**hetzner-k3s** is a CLI tool that creates production-ready Kubernetes clusters on [Hetzner Cloud](https://hetzner.cloud/?ref=mqx6KKKwyook) in minutes, not hours. No Terraform to learn, no management cluster required, no third-party access to your credentials.\n\n### Speed That Sets Records\n\n- **3-node HA cluster in 2-3 minutes** — masters, workers, networking, and essential components all configured\n- **500-node cluster in under 11 minutes** — tested with 3 masters and 497 workers (possibly a world record!)\n\n### Simplicity Without Compromise\n\n- **Single CLI tool** — no Terraform, Packer, Ansible, or existing Kubernetes cluster required\n- **One YAML config file** — human-readable configuration, version-controllable\n- **Batteries included** — Cloud Controller Manager, CSI driver, System Upgrade Controller, and Cluster Autoscaler installed automatically\n\n### Complete Control, Zero Lock-in\n\n- **Your credentials stay local** — Hetzner API token never leaves your machine\n- **No third-party access** — unlike managed services, no one else can see your clusters or workloads\n- **Open source (MIT License)** — inspect, modify, and contribute to the code\n- **No recurring platform fees** — you only pay Hetzner for infrastructure\n\n### How It Works\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"diagram.svg\" alt=\"How hetzner-k3s works\" width=\"700\"\u003e\n\u003c/p\u003e\n\nNo Terraform. No Packer. No Ansible. No management cluster. No third-party account. Your API token never leaves your machine.\n\n---\n\n## Why Hetzner Cloud + k3s?\n\n### Hetzner Cloud: Exceptional Value\n\n[Hetzner Cloud](https://hetzner.cloud/?ref=mqx6KKKwyook) offers the best performance-to-cost ratio in the industry:\n\n- **Up to 80% lower costs** than AWS, Google Cloud, and Azure\n- **Transparent pricing** — traffic, IPv4/IPv6, DDoS protection, and firewalls included\n- **Global presence** — data centers in Germany (Nuremberg, Falkenstein), Finland (Helsinki), USA (Ashburn, Hillsboro), and Singapore\n- **Flexible instance types** — x86 and ARM architectures, including cost-effective ARM instances (CAX) for budget-friendly clusters\n- **Proven reliability** — trusted by companies worldwide for over 25 years\n\n### k3s: Lightweight Kubernetes\n\n[k3s](https://k3s.io/) by Rancher is a certified Kubernetes distribution optimized for resource efficiency:\n\n- **Lower resource footprint** — uses less memory and CPU, leaving more for your workloads\n- **Single binary** — fast to deploy and upgrade\n- **Production-ready** — 99.8% successful automated updates in community benchmarks\n\n### Sample Monthly Costs\n\nReal infrastructure costs for common cluster configurations (December 2025 pricing):\n\n| Cluster Type | Configuration | Monthly Cost |\n|--------------|---------------|--------------|\n| **Development** | 1 master (CX23), 2 workers (CX23) | ~€16/month |\n| **Small Production** | 3 masters (CPX22), 3 workers (CPX32) | ~€58/month |\n| **Medium Production** | 3 masters (CPX22), 10 workers (CPX32) | ~€135/month |\n| **Large Production** | 3 masters (CPX42), 50 workers (CPX32) | ~€615/month |\n\n*Includes load balancer (~€5.50/month). No management fees, no per-user fees—just infrastructure.*\n\n**Compare to managed alternatives:**\n- Equivalent AWS EKS: 3-5x higher infrastructure cost + $0.10/hour cluster fee (~$73/month)\n- Managed Hetzner services (e.g. Cloudfleet): Infrastructure + platform fees that scale with cluster size and add up quickly\n\n---\n\n## What Gets Installed\n\nWhen you run `hetzner-k3s create`, you get a complete, production-ready cluster:\n\n| Component | Purpose |\n|-----------|---------|\n| **k3s** | Lightweight Kubernetes distribution |\n| **[Hetzner Cloud Controller Manager](https://github.com/hetznercloud/hcloud-cloud-controller-manager)** | Automatic load balancer provisioning |\n| **[Hetzner CSI Driver](https://github.com/hetznercloud/csi-driver)** | Persistent volumes via Hetzner block storage |\n| **[System Upgrade Controller](https://github.com/rancher/system-upgrade-controller)** | Zero-downtime k3s upgrades |\n| **[Cluster Autoscaler](https://github.com/kubernetes/autoscaler)** | Automatic node scaling based on demand |\n\nAll integrated with Hetzner's private networking and firewall. Traefik, ServiceLB, and metrics-server are available as optional add-ons.\n\n---\n\n## Quick Start\n\n### 1. Install hetzner-k3s\n\n**Homebrew (macOS/Linux):**\n```bash\nbrew install vitobotta/tap/hetzner_k3s\n```\n\n**Linux binary (amd64):**\n```bash\nwget https://github.com/vitobotta/hetzner-k3s/releases/download/v2.4.6/hetzner-k3s-linux-amd64\nchmod +x hetzner-k3s-linux-amd64\nsudo mv hetzner-k3s-linux-amd64 /usr/local/bin/hetzner-k3s\n```\n\nSee [Installation Guide](https://vitobotta.github.io/hetzner-k3s/Installation/) for all platforms.\n\n### 2. Create a Configuration File\n\nCreate `cluster.yaml`:\n\n```yaml\nhetzner_token: \u003cyour-token\u003e\ncluster_name: my-cluster\nkubeconfig_path: \"./kubeconfig\"\nk3s_version: v1.32.0+k3s1\n\nnetworking:\n  ssh:\n    port: 22\n    use_agent: false\n    public_key_path: \"~/.ssh/id_ed25519.pub\"\n    private_key_path: \"~/.ssh/id_ed25519\"\n  allowed_networks:\n    ssh:\n      - 0.0.0.0/0\n    api:\n      - 0.0.0.0/0\n\nmasters_pool:\n  instance_type: cpx22\n  instance_count: 3\n  locations:\n    - fsn1\n    - hel1\n    - nbg1\n\nworker_node_pools:\n- name: workers\n  instance_type: cpx32\n  instance_count: 3\n  location: hel1\n```\n\nSee [Creating a Cluster](https://vitobotta.github.io/hetzner-k3s/Creating_a_cluster/) for a complete configuration example with all available options.\n\n### 3. Create Your Cluster\n\n```bash\nhetzner-k3s create --config cluster.yaml\n```\n\nIn 2-3 minutes, your cluster is ready. The kubeconfig is saved automatically.\n\n```bash\nexport KUBECONFIG=./kubeconfig\nkubectl get nodes\n```\n\n---\n\n## Who Uses hetzner-k3s?\n\n- **Startups** running cost-efficient production workloads\n- **Development teams** spinning up ephemeral test clusters\n- **Agencies and consultants** deploying client infrastructure quickly\n- **Companies** in regulated industries requiring data sovereignty\n- **Platform engineers** who want simplicity without sacrificing control\n\nJoin an active community with 3,100+ GitHub stars and regular contributions.\n\n---\n\n## How It Compares\n\n| Factor | hetzner-k3s | Managed Services | Terraform-based |\n|--------|-------------|------------------|-----------------|\n| **Setup time** | 2-3 minutes | 5-10 minutes | 15-30+ minutes |\n| **Dependencies** | CLI tool only | Third-party account* | Terraform, Packer, HCL knowledge |\n| **Data privacy** | Full control | Third-party access | Full control |\n| **Monthly cost** | Infrastructure only | Infrastructure + platform fees | Infrastructure only |\n| **Credential exposure** | None | API tokens to third party | None |\n| **Learning curve** | Low | Low | Medium-High |\n\n*Managed services (Cloudfleet, Edka, etc.) require signing up for their platform in addition to Hetzner Cloud.\n\nFor a detailed comparison, see [Why hetzner-k3s Stands Out](https://vitobotta.github.io/hetzner-k3s/Comparison_with_other_tools/).\n\n---\n\n## Key Features\n\n### High Availability\nDeploy masters and worker pools across multiple locations for regional resilience.\n\n### Autoscaling\nDefine min/max instances per node pool. The Cluster Autoscaler handles the rest.\n\n```yaml\nworker_node_pools:\n- name: autoscaled\n  instance_type: cpx32\n  location: fsn1\n  autoscaling:\n    enabled: true\n    min_instances: 1\n    max_instances: 10\n```\n\n### Multiple Node Pools\nMix 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.\n\n### Private Networking\nCluster communication over Hetzner's private network by default.\n\n### CNI Options\nChoose Flannel (simple) or Cilium (advanced networking features).\n\n### Large Cluster Support\nTested with 500 nodes and designed to scale beyond. Clusters over 100 nodes require some configuration changes (see [Recommendations](https://vitobotta.github.io/hetzner-k3s/Recommendations/)).\n\n---\n\n## Documentation\n\nFull documentation: **[vitobotta.github.io/hetzner-k3s](https://vitobotta.github.io/hetzner-k3s/)**\n\n- [Installation](https://vitobotta.github.io/hetzner-k3s/Installation/)\n- [Creating a Cluster](https://vitobotta.github.io/hetzner-k3s/Creating_a_cluster/)\n- [Setting Up a Complete Stack](https://vitobotta.github.io/hetzner-k3s/Setting_up_a_cluster/)\n- [Cluster Maintenance](https://vitobotta.github.io/hetzner-k3s/Maintenance/)\n- [Recommendations for Production](https://vitobotta.github.io/hetzner-k3s/Recommendations/)\n- [Troubleshooting](https://vitobotta.github.io/hetzner-k3s/Troubleshooting/)\n\n---\n\n## Who am I?\n\nI'm Vito Botta, Lead Platform Architect at [Brella](https://www.brella.io/), an event management platform based in Finland. I handle infrastructure, coding, and support for the development team.\n\nI also spend time as a bug bounty hunter, finding and responsibly reporting security vulnerabilities.\n\nConnect with me at [vitobotta.com](https://vitobotta.com/). I'm available for consultancies around hetzner-k3s and Kubernetes on Hetzner.\n\n---\n\n## Why Sponsor?\n\nThis project is maintained by a single developer in my spare time. Sponsorship helps me:\n\n- Respond to issues faster\n- Ship new features regularly\n- Keep the project compatible with new Hetzner Cloud updates\n\nIf hetzner-k3s saves you time or money, please consider [supporting its development](https://github.com/sponsors/vitobotta).\n\n### Platinum Sponsors\n\n\u003ca href=\"https://sprintpulse.io/?utm_source=github\u0026utm_medium=social\u0026utm_campaign=hetzner-k3s\u0026utm_content=readme\"\u003e\u003cimg src=\"SprintPulse.svg\" alt=\"SprintPulse\" height=\"80\"\u003e\u003c/a\u003e\n\n[SprintPulse](https://sprintpulse.io/?utm_source=github\u0026utm_medium=social\u0026utm_campaign=hetzner-k3s\u0026utm_content=readme) — the retrospective tool teams actually love. Run engaging retros with real-time collaboration, AI-powered insights, and actionable outcomes. Set up in 60 seconds, no training required.\n\n\u003ca href=\"https://alamos.gmbh\"\u003e\u003cimg src=\"Alamos_black.svg\" alt=\"Alamos GmbH\" height=\"80\"\u003e\u003c/a\u003e\n\nA special thank you to [Alamos GmbH](https://alamos.gmbh) for sponsoring the development of key features!\n\n### Backers\n\nThanks to [@deubert-it](https://github.com/deubert-it), [@jonasbadstuebner](https://github.com/jonasbadstuebner), [@ricristian](https://github.com/ricristian), [@QuentinFAIDIDE](https://github.com/QuentinFAIDIDE) for their support!\n\n---\n\n## Contributing\n\nContributions are welcome! See [Contributing and Support](https://vitobotta.github.io/hetzner-k3s/Contributing_and_support/) for guidelines.\n\n## Code of Conduct\n\nEveryone interacting in this project is expected to follow the [code of conduct](https://github.com/vitobotta/hetzner-k3s/blob/main/CODE_OF_CONDUCT.md).\n\n## License\n\nOpen source under the [MIT License](https://github.com/vitobotta/hetzner-k3s/blob/main/LICENSE.txt).\n\n---\n\n## Star History\n\n[![Stargazers over time](https://starchart.cc/vitobotta/hetzner-k3s.svg)](https://starchart.cc/vitobotta/hetzner-k3s)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvitobotta%2Fhetzner-k3s","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvitobotta%2Fhetzner-k3s","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvitobotta%2Fhetzner-k3s/lists"}