{"id":15065997,"url":"https://github.com/duncanpierce/hetzanetes","last_synced_at":"2025-10-23T02:28:49.828Z","repository":{"id":38409808,"uuid":"296830442","full_name":"duncanpierce/hetzanetes","owner":"duncanpierce","description":"Create self-managing Rancher K3s Kubernetes clusters on Hetzner Cloud","archived":false,"fork":false,"pushed_at":"2023-10-11T23:42:57.000Z","size":272,"stargazers_count":10,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T12:21:25.984Z","etag":null,"topics":["golang","hetzner-cloud","k3s","k3s-cluster","k8s","k8s-cluster","kubernetes","kubernetes-cluster"],"latest_commit_sha":null,"homepage":"","language":"Go","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/duncanpierce.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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}},"created_at":"2020-09-19T09:16:37.000Z","updated_at":"2024-01-27T21:35:23.000Z","dependencies_parsed_at":"2024-06-20T17:14:55.065Z","dependency_job_id":"b55c700e-91e3-4fb6-b082-3baf5d4ecb8d","html_url":"https://github.com/duncanpierce/hetzanetes","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duncanpierce%2Fhetzanetes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duncanpierce%2Fhetzanetes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duncanpierce%2Fhetzanetes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duncanpierce%2Fhetzanetes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/duncanpierce","download_url":"https://codeload.github.com/duncanpierce/hetzanetes/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248225878,"owners_count":21068079,"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":["golang","hetzner-cloud","k3s","k3s-cluster","k8s","k8s-cluster","kubernetes","kubernetes-cluster"],"created_at":"2024-09-25T00:59:18.346Z","updated_at":"2025-10-23T02:28:49.478Z","avatar_url":"https://github.com/duncanpierce.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![CodeQL](https://github.com/duncanpierce/hetzanetes/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/duncanpierce/hetzanetes/actions/workflows/github-code-scanning/codeql)\n\n# Hetzanetes\n\nCreate self-managing [Rancher](https://www.rancher.com/products/k3s) [K3s](https://github.com/k3s-io/k3s) Kubernetes clusters on [Hetzner Cloud](https://www.hetzner.com/cloud).\n\n* The cluster manages itself using a `Cluster` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).\n* Avoids local configuration files. You can reconfigure the cluster using `kubectl edit cluster/\u003cNAME\u003e`. The cluster can even reconfigure itself.\n* Self-repairing, so if a node is deleted, Hetzanetes will replace it.\n* Number of API servers and workers can be changed without stopping the cluster.\n* Sets up Rancher's lightweight [K3s Kubernetes distribution](https://github.com/rancher/k3s/).\n* Sets up a firewall and private network for the cluster.\n* Install Hetzner's [cloud controller manager](https://github.com/hetznercloud/hcloud-cloud-controller-manager) and [storage volume](https://github.com/hetznercloud/csi-driver) plugins, so volume and load balancer resources work.\n\n## Current limitations\n\n* Downsizing the API server node set can hang the cluster. Worker node pools can be downsized.\n* Cannot manage other clusters, even though you could have more than one `Cluster` resource, in theory.\n\n## Getting started\n\n1. Create a Hetzner Cloud project, if you don't already have one. If this is your first time using Hetzner Cloud, you can get [free service credit using this referral link](https://hetzner.cloud/?ref=0obWH96gyXNL) (disclosure: I may also receive a service credit).\n2. Create a read+write API Token in that project (under **Security \u003e API Tokens**), if you don't already have one.\n3. Assign the API Token to an environment variable named `HCLOUD_TOKEN`.\n4. Run `hetzanetes create test` to create a cluster called `test`. Or, using Docker: `docker run -e HCLOUD_TOKEN ghcr.io/duncanpierce/hetzanetes create test`.\n5. Wait patiently while a private network, firewall and first Kubernetes API server are created, security updates are installed, server rebooted, Hetzner's Kubernetes plugins installed.\n6. Once ready, the first API server will read the `Cluster` custom resource and create more API servers and workers as needed.\n7. From this point on, the cluster is self-managing. The complete process takes around 10 minutes using CX11 servers.\n8. You can now log into any of the API servers and use `kubectl edit cluster/test` (or whatever cluster name you chose) to reconfigure the cluster.\n\n## Configuring the cluster before creation\n\nSave this example as a file named `cluster.yaml` then customise it with the server nodes you want.\nThis example has a single set of API server nodes and two sets of worker nodes.\n\n```yaml\napiVersion: hetzanetes.duncanpierce.org/v1\nkind: Cluster\nmetadata:\n  name: example\nspec:\n  versions:\n    baseImage: ubuntu-22.04\n    kubernetes: stable\n    hetzanetes: latest\n  nodeSets:\n    - name: api\n      apiServer: true\n      serverType: cpx21\n      replicas: 3\n      locations:\n        - hel1\n        - fsn1\n        - nbg1\n    - name: worker-pool-a\n      serverType: cpx11\n      replicas: 2\n      locations:\n        - hel1\n        - fsn1\n    - name: worker-pool-b\n      serverType: cpx11\n      replicas: 1\n      locations:\n        - nbg1\n```\n\nThen run `hetzanetes create -f cluster.yaml` to create the first API server node. This will then create the rest of the cluster.\n\n## In future\n\n* Release prebuild executables to avoid building hetzanetes yourself.\n* Automate security updates.\n* Automate K3s distribution updates.\n* Synchronize SSH keys the cluster will accept with those registered in the Hetzner API - handy if your lose you private key or your team changes.\n* Make SSH recognise new Hetzner servers so we don't get \"key changed\" errors.\n* Include workloads at creation time to be run in the cluster once it's ready.\n* Make it easy to download the kube config file.\n* Optionally create a load balancer for the API servers to make it easier to use `kubectl` remotely.\n\n## Alternatives\n\nI wanted a simple way to create and manage Kubernetes clusters on Hetzner Cloud, and I wanted to be able to manage\nand repair the cluster from within. There are really good projects out there but none of them quite did what I wanted (as of 2020-09-19).\nThey are all worth checking out, especially if this project doesn't meet your needs.\n\n* [Pharmer](https://github.com/pharmer/pharmer) - loads of features but doesn't support Hetzner Cloud.\n* [Hetzner-Kube](https://github.com/xetys/hetzner-kube) - impressive networking setup dates from before Hetzner Cloud had private networks, load balancers and labels. Uses `kubeadm`.\n* [K3sup](https://github.com/alexellis/k3sup) - great way to install Rancher's K3s Kubernetes on a cluster but it doesn't provision the cluster or up a firewall.\n* [Kube-Hetzner](https://github.com/mysticaltech/kube-hetzner) - uses Terraform to set up K3OS\n* [kubernetes-on-hetzner](https://github.com/LWJ/kubernetes-on-hetzner) - uses Terraform\n* [hetzner-k3s](https://github.com/vitobotta/hetzner-k3s) - Vito Botta's more recent project - very complete but manages the cluster from outside\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduncanpierce%2Fhetzanetes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fduncanpierce%2Fhetzanetes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduncanpierce%2Fhetzanetes/lists"}