{"id":13550769,"url":"https://github.com/hetznercloud/hcloud-cloud-controller-manager","last_synced_at":"2025-05-14T12:12:20.587Z","repository":{"id":37396901,"uuid":"118783793","full_name":"hetznercloud/hcloud-cloud-controller-manager","owner":"hetznercloud","description":"Kubernetes cloud-controller-manager for Hetzner Cloud","archived":false,"fork":false,"pushed_at":"2025-05-07T02:01:22.000Z","size":42774,"stargazers_count":788,"open_issues_count":32,"forks_count":120,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-05-07T03:18:40.075Z","etag":null,"topics":["hcloud","hetzner","hetzner-cloud","kubernetes"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hetznercloud.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-01-24T15:27:24.000Z","updated_at":"2025-05-07T02:00:31.000Z","dependencies_parsed_at":"2023-10-20T11:34:09.769Z","dependency_job_id":"e034c1f9-c507-40f3-a988-67eae8cc0603","html_url":"https://github.com/hetznercloud/hcloud-cloud-controller-manager","commit_stats":{"total_commits":453,"total_committers":49,"mean_commits":9.244897959183673,"dds":0.6909492273730684,"last_synced_commit":"23167695206461143c07a29288f2c6812133c5f4"},"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hetznercloud%2Fhcloud-cloud-controller-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hetznercloud%2Fhcloud-cloud-controller-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hetznercloud%2Fhcloud-cloud-controller-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hetznercloud%2Fhcloud-cloud-controller-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hetznercloud","download_url":"https://codeload.github.com/hetznercloud/hcloud-cloud-controller-manager/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254140768,"owners_count":22021220,"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":["hcloud","hetzner","hetzner-cloud","kubernetes"],"created_at":"2024-08-01T12:01:37.378Z","updated_at":"2025-05-14T12:12:20.574Z","avatar_url":"https://github.com/hetznercloud.png","language":"Go","funding_links":[],"categories":["Go","Integrations","kubernetes"],"sub_categories":["Rust"],"readme":"# Kubernetes Cloud Controller Manager for Hetzner Cloud\n\n[![e2e tests](https://github.com/hetznercloud/hcloud-cloud-controller-manager/actions/workflows/test_e2e.yml/badge.svg)](https://github.com/hetznercloud/hcloud-cloud-controller-manager/actions/workflows/test_e2e.yml)\n[![Codecov](https://codecov.io/github/hetznercloud/hcloud-cloud-controller-manager/graph/badge.svg?token=Q7pbOoyVpj)](https://codecov.io/github/hetznercloud/hcloud-cloud-controller-manager/tree/main)\n\nThe Hetzner Cloud [cloud-controller-manager](https://kubernetes.io/docs/concepts/architecture/cloud-controller/) integrates your Kubernetes cluster with the Hetzner Cloud \u0026 Robot APIs.\n\n## Features\n\n- **Node**:\n  - Updates your `Node` objects with information about the server from the Cloud \u0026 Robot API.\n  - Instance Type, Location, Datacenter, Server ID, IPs.\n- **Node Lifecycle**:\n  - Cleans up stale `Node` objects when the server is deleted in the API.\n- **Routes** (if enabled):\n  - Routes traffic to the pods through Hetzner Cloud Networks. Removes one layer of indirection in CNIs that support this.\n- **Load Balancer**:\n  - Watches Services with `type: LoadBalancer` and creates Hetzner Cloud Load Balancers for them, adds Kubernetes Nodes as targets for the Load Balancer.\n\nRead more about cloud controllers in the [Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/running-cloud-controller/).\n\n### Node Metadata Example\n\n```yaml\napiVersion: v1\nkind: Node\nmetadata:\n  labels:\n    node.kubernetes.io/instance-type: cx22\n    topology.kubernetes.io/region: fsn1\n    topology.kubernetes.io/zone: fsn1-dc8\n    instance.hetzner.cloud/provided-by: cloud\n  name: node\nspec:\n  podCIDR: 10.244.0.0/24\n  providerID: hcloud://123456 # \u003c-- Hetzner Cloud Server ID\nstatus:\n  addresses:\n    - address: node\n      type: Hostname\n    - address: 1.2.3.4 # \u003c-- Hetzner Cloud Server public ipv4\n      type: ExternalIP\n```\n\n## Deployment\n\nThis deployment example uses `kubeadm` to bootstrap an Kubernetes\ncluster, with [flannel](https://github.com/coreos/flannel) as overlay\nnetwork agent. Feel free to adapt the steps to your preferred method of\ninstalling Kubernetes.\n\nThese deployment instructions are designed to guide with the\ninstallation of the `hcloud-cloud-controller-manager` and are by no\nmeans an in depth tutorial of setting up Kubernetes clusters.\n**Previous knowledge about the involved components is required.**\n\nPlease refer to the [kubeadm cluster creation\nguide](https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/),\nwhich these instructions are meant to augment and the [kubeadm\ndocumentation](https://kubernetes.io/docs/reference/setup-tools/kubeadm/kubeadm/).\n\n1. The cloud controller manager adds the labels when a node is added to\n   the cluster. For current Kubernetes versions, this means we\n   have to add the `--cloud-provider=external` flag to the `kubelet`. How you\n   do this depends on your Kubernetes distribution. With `kubeadm` you can\n   either set it in the kubeadm config\n   ([`nodeRegistration.kubeletExtraArgs`][kubeadm-config]) or through a systemd\n   drop-in unit `/etc/systemd/system/kubelet.service.d/20-hcloud.conf`:\n\n   ```ini\n   [Service]\n   Environment=\"KUBELET_EXTRA_ARGS=--cloud-provider=external\"\n   ```\n\n   Note: the `--cloud-provider` flag is deprecated since K8S 1.19. You\n   will see a log message regarding this. For now (v1.32) it is still required.\n\n2. Now the control plane can be initialized:\n\n   ```sh\n   sudo kubeadm init --pod-network-cidr=10.244.0.0/16\n   ```\n\n3. Configure kubectl to connect to the kube-apiserver:\n\n   ```sh\n   mkdir -p $HOME/.kube\n   sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config\n   sudo chown $(id -u):$(id -g) $HOME/.kube/config\n   ```\n\n4. Deploy the flannel CNI plugin:\n\n   ```sh\n   kubectl apply -f https://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.yml\n   ```\n\n5. Patch the flannel deployment to tolerate the `uninitialized` taint:\n\n   ```sh\n   kubectl -n kube-system patch ds kube-flannel-ds --type json -p '[{\"op\":\"add\",\"path\":\"/spec/template/spec/tolerations/-\",\"value\":{\"key\":\"node.cloudprovider.kubernetes.io/uninitialized\",\"value\":\"true\",\"effect\":\"NoSchedule\"}}]'\n   ```\n\n6. Create a secret containing your Hetzner Cloud API token.\n\n   ```sh\n   kubectl -n kube-system create secret generic hcloud --from-literal=token=\u003chcloud API token\u003e\n   ```\n\n7. Deploy `hcloud-cloud-controller-manager`\n\n   **Using Helm (recommended):**\n\n   ```\n   helm repo add hcloud https://charts.hetzner.cloud\n   helm repo update hcloud\n   helm install hccm hcloud/hcloud-cloud-controller-manager -n kube-system\n   ```\n\n   See the [Helm chart README](./chart/README.md) for more info.\n\n   **Legacy installation method**:\n\n   ```sh\n   kubectl apply -f https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/latest/download/ccm.yaml\n   ```\n\n[kubeadm-config]: https://kubernetes.io/docs/reference/config-api/kubeadm-config.v1beta4/#kubeadm-k8s-io-v1beta4-NodeRegistrationOptions\n\n## Networks support\n\nWhen you use the Cloud Controller Manager with networks support, the CCM is in favor of allocating the IPs (\u0026 setup the\nrouting) (Docs: https://kubernetes.io/docs/concepts/architecture/cloud-controller/#route-controller). The CNI plugin you\nuse needs to support this k8s native functionality (Cilium does it, I don't know about Calico \u0026 WeaveNet), so basically\nyou use the Hetzner Cloud Networks as the underlying networking stack.\n\nWhen you use the CCM without Networks support it just disables the RouteController part, all other parts work completely\nthe same. Then just the CNI is in charge of making all the networking stack things. Using the CCM with Networks support\nhas the benefit that your node is connected to a private network so the node doesn't need to encrypt the connections and\nyou have a bit less operational overhead as you don't need to manage the Network.\n\nIf you want to use the Hetzner Cloud `Networks` Feature, head over to\nthe [Deployment with Networks support\ndocumentation](./docs/deploy_with_networks.md).\n\nIf you manage the network yourself it might still be required to let the CCM know about private networks. For example,\neven with a self-managed network, it's still possible to enable private network attachment of CCM-provisioned Load\nBalancers by setting the `load-balancer.hetzner.cloud/use-private-ip` annotation to `true` on the Kubernetes Service.\nThis functionality requires setting the following environment variables in the CCM deployment:\n\n```\n          env:\n            - name: HCLOUD_NETWORK\n              valueFrom:\n                secretKeyRef:\n                  name: hcloud\n                  key: network\n            - name: HCLOUD_NETWORK_ROUTES_ENABLED\n              value: \"false\"\n```\n\nYou also need to add the network name/ID to the\nsecret: `kubectl -n kube-system create secret generic hcloud --from-literal=token=\u003chcloud API token\u003e --from-literal=network=\u003chcloud Network_ID_or_Name\u003e`\n.\n\n## Kube-proxy mode IPVS and HCloud LoadBalancer\n\nIf `kube-proxy` is run in IPVS mode, the `Service` manifest needs to have the\nannotation `load-balancer.hetzner.cloud/hostname` where the FQDN resolves to the HCloud LoadBalancer IP.\n\nSee https://github.com/hetznercloud/hcloud-cloud-controller-manager/issues/212\n\n## Versioning policy\n\nWe aim to support the latest three versions of Kubernetes. When a Kubernetes\nversion is marked as _End Of Life_, we will stop support for it and remove the\nversion from our CI tests. This does not necessarily mean that the\nCloud Controller Manager does not still work with this version. We will\nnot fix bugs related only to an unsupported version.\n\nCurrent Kubernetes Releases: https://kubernetes.io/releases/\n\n### With Networks support\n\n| Kubernetes | Cloud Controller Manager |                                                                                             Deployment File |\n| ---------- | -----------------------: | ----------------------------------------------------------------------------------------------------------: |\n| 1.32       |                   latest |  https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/latest/download/ccm-networks.yaml |\n| 1.31       |                   latest |  https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/latest/download/ccm-networks.yaml |\n| 1.30       |                   latest |  https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/latest/download/ccm-networks.yaml |\n| 1.29       |                   latest |  https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/latest/download/ccm-networks.yaml |\n| 1.28       |                  v1.20.0 | https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/download/v1.20.0/ccm-networks.yaml |\n| 1.27       |                  v1.20.0 | https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/download/v1.20.0/ccm-networks.yaml |\n| 1.26       |                  v1.19.0 | https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/download/v1.19.0/ccm-networks.yaml |\n| 1.25       |                  v1.19.0 | https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/download/v1.19.0/ccm-networks.yaml |\n| 1.24       |                  v1.17.2 | https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/download/v1.17.2/ccm-networks.yaml |\n| 1.23       |                  v1.13.2 | https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/download/v1.13.2/ccm-networks.yaml |\n\n### Without Networks support\n\n| Kubernetes | Cloud Controller Manager |                                                                                    Deployment File |\n| ---------- | -----------------------: | -------------------------------------------------------------------------------------------------: |\n| 1.32       |                   latest |  https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/latest/download/ccm.yaml |\n| 1.31       |                   latest |  https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/latest/download/ccm.yaml |\n| 1.30       |                   latest |  https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/latest/download/ccm.yaml |\n| 1.29       |                   latest |  https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/latest/download/ccm.yaml |\n| 1.28       |                  v1.20.0 | https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/download/v1.20.0/ccm.yaml |\n| 1.27       |                  v1.20.0 | https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/download/v1.20.0/ccm.yaml |\n| 1.26       |                  v1.19.0 | https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/download/v1.19.0/ccm.yaml |\n| 1.25       |                  v1.19.0 | https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/download/v1.19.0/ccm.yaml |\n| 1.24       |                  v1.17.2 | https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/download/v1.17.2/ccm.yaml |\n| 1.23       |                  v1.13.2 | https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/download/v1.13.2/ccm.yaml |\n\n## Development\n\n### Setup a development environment\n\nTo set up a development environment, make sure you installed the following tools:\n\n- [tofu](https://opentofu.org/)\n- [k3sup](https://github.com/alexellis/k3sup)\n- [docker](https://www.docker.com/)\n- [skaffold](https://skaffold.dev/)\n\n1. Configure a `HCLOUD_TOKEN` in your shell session.\n\n\u003e [!WARNING]\n\u003e The development environment runs on Hetzner Cloud servers which will induce costs.\n\n2. Deploy the development cluster:\n\n```sh\nmake -C dev up\n```\n\n3. Load the generated configuration to access the development cluster:\n\n```sh\nsource dev/files/env.sh\n```\n\n4. Check that the development cluster is healthy:\n\n```sh\nkubectl get nodes -o wide\n```\n\n5. Start developing hcloud-cloud-controller-manager in the development cluster:\n\n```sh\nskaffold dev\n```\n\nOn code change, skaffold will rebuild the image, redeploy it and print all logs.\n\n⚠️ Do not forget to clean up the development cluster once are finished:\n\n```sh\nmake -C dev down\n```\n\n### Run the unit tests\n\nTo run the unit tests, make sure you installed the following tools:\n\n- [Go](https://go.dev/)\n\n1. Run the following command to run the unit tests:\n\n```sh\ngo test ./...\n```\n\n### Run the kubernetes e2e tests\n\nBefore running the e2e tests, make sure you followed the [Setup a development environment](#setup-a-development-environment) steps.\n\n1. Run the kubernetes e2e tests using the following command:\n\n```sh\nsource dev/files/env.sh\ngo test ./tests/e2e -tags e2e -v\n```\n\n### Development with Robot\n\nIf you want to work on the Robot support, you need to make some changes to the above setup.\n\nThis requires that you have a Robot Server in the same account you use for the development. The server needs to be setup with the Ansible Playbook `dev/robot/install.yml` and configured in `dev/robot/install.yml`.\n\n1. Set these environment variables:\n\n```shell\nexport ROBOT_ENABLED=true\n\nexport ROBOT_USER=\u003cYour Robot User\u003e\nexport ROBOT_PASSWORD=\u003cYour Robot Password\u003e\n```\n\n2. Continue with the environment setup until you reach the `skaffold` step. Run `skaffold dev --profile=robot` instead.\n\n3. We have another suite of tests for Robot. You can run these with:\n\n```sh\ngo test ./tests/e2e -tags e2e,robot -v\n```\n\n## License\n\nApache License, Version 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhetznercloud%2Fhcloud-cloud-controller-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhetznercloud%2Fhcloud-cloud-controller-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhetznercloud%2Fhcloud-cloud-controller-manager/lists"}