Kubernetes Cloud Controller Manager for Hetzner Cloud

[!IMPORTANT]

If you are running hcloud-cloud-controller-manager in version <= v1.30.0, please update as soon as possible to at least v1.30.1. The server.datacenter field was deprecated and has been removed from the API response since 2026-07-01 (see changelog). Deployments of hcloud-cloud-controller-manager that were not updated before the field was removed from the API will panic and crash.

On 2026-07-07 we deleted the latest image tag. It was broken and heavily outdated (last updated three years ago), so it should not be relied upon. Always pin your deployment to a specific released version instead. See the releases for available versions.

The Hetzner Cloud cloud-controller-manager integrates your Kubernetes cluster with the Hetzner Cloud & Robot APIs.

Docs

• :rocket: See the quick start guide to get you started.
• :book: See the configuration reference for the available configuration.

Development

Setup a development environment

To set up a development environment, make sure you installed the following tools:

• tofu
• k3sup
• docker
• skaffold

• Configure a HCLOUD_TOKEN in your shell session.

[!WARNING]

The development environment runs on Hetzner Cloud servers which will induce costs.

• Deploy the development cluster:

make -C dev up

• Load the generated configuration to access the development cluster:

source dev/files/env.sh

• Check that the development cluster is healthy:

kubectl get nodes -o wide

• Start developing hcloud-cloud-controller-manager in the development cluster:

skaffold dev

On code change, skaffold will rebuild the image, redeploy it and print all logs.

⚠️ Do not forget to clean up the development cluster once you are finished:

make -C dev down

Run the unit tests

To run the unit tests, make sure you installed the following tools:

• Go

• Run the following command to run the unit tests:

go test ./...

Run the kubernetes e2e tests

Before running the e2e tests, make sure you followed the Setup a development environment steps.

• Run the kubernetes e2e tests using the following command:

source dev/files/env.sh
go test ./tests/e2e -tags e2e -v

Development with Robot

If you want to work on the Robot support, you need to make some changes to the above setup.

This 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.

• Set these environment variables:

export ROBOT_ENABLED=true
export ROBOT_USER=<Your Robot User> export ROBOT_PASSWORD=<Your Robot Password>

• Continue with the environment setup until you reach the skaffold step. Run skaffold dev --profile=robot instead.

• We have another suite of tests for Robot. You can run these with:

go test ./tests/e2e -tags e2e,robot -v

Annotation and Environment Variable Reference Generation

The Load Balancer annotation reference and the Load Balancer environment variable reference are autogenerated via a custom written tool. This tool can be found at tools/doc_generation.go.

The docstring format contains a description, starting with the constant name. The next lines can contain additional information about the annotation. Supported fields are:

• Type: Specifies the type of the annotation. If the annotation is an enum, all possible values need to be separated via a pipe symbol |.
• Default: Specifies the default value of the annotation. When no default value is set, - is displayed.
• Read-only: Specifies whether the annotation is read-only or not. If the annotation is read-only, it will be set by the HCCM and cannot be set by the user.
• Internal: Specifies whether the annotation is for internal use only. If the annotation is internal, it will not be displayed in the reference documentation.
• You can reference other annotations or env vars by wrapping the target constant name in square brackets, e.g. [LBAlgorithmType].

Example

// LBAlgorithmType specifies the algorithm type of the Load Balancer.
//
// Type: roundrobin | leastconnections
// Default: round_robin
LBAlgorithmType Name = "load-balancer.hetzner.cloud/algorithm-type"

License

Apache License, Version 2.0