KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #typescript #codex #claude-code #mcp #rust #deepseek-harness #ai-agent #cli

hcloud-cloud-controller-manager

★ 922 Open GitHub ↗

Kubernetes cloud-controller-manager for Hetzner Cloud

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Kubernetes Cloud Controller Manager for Hetzner Cloud

[![Tests](https://github.com/hetznercloud/hcloud-cloud-controller-manager/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/hetznercloud/hcloud-cloud-controller-manager/actions/workflows/test.yml)
[![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)

> [!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](https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases/tag/v1.30.1). The `server.datacenter` field was deprecated and has been removed from the API response since 2026-07-01 ([see changelog](https://docs.hetzner.cloud/changelog#2025-12-16-phasing-out-datacenters)). 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](https://github.com/hetznercloud/hcloud-cloud-controller-manager/releases) for available versions.

The Hetzner Cloud [cloud-controller-manager](https://kubernetes.io/docs/concepts/architecture/cloud-controller/) integrates your Kubernetes cluster with the Hetzner Cloud & Robot APIs.

## Docs

- :rocket: See the [quick start guide](docs/guides/quickstart.md) to get you started.
- :book: See the [configuration reference](docs/reference/README.md) for the available configuration.

For more information, see the [documentation](docs/).

## Development

### Setup a development environment

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

- [tofu](https://opentofu.org/)
- [k3sup](https://github.com/alexellis/k3sup)
- [docker](https://www.docker.com/)
- [skaffold](https://skaffold.dev/)

1. Configure a `HCLOUD_TOKEN` in your shell session.

> [!WARNING]
> The development environment runs on Hetzner Cloud servers which will induce costs.

2. Deploy the development cluster:

```sh
make -C dev up
```

3. Load the generated configuration to access the development cluster:

```sh
source dev/files/env.sh
```

4. Check that the development cluster is healthy:

```sh
kubectl get nodes -o wide
```

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

```sh
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:

```sh
make -C dev down
```

### Run the unit tests

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

- [Go](https://go.dev/)

1. Run the following command to run the unit tests:

```sh
go test ./...
```

### Run the kubernetes e2e tests

Before running the e2e tests, make sure you followed the [Setup a development environment](#setup-a-development-environment) steps.

1. Run the kubernetes e2e tests using the following command:

```sh
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`.

1. Set these environment variables:

```shell
export ROBOT_ENABLED=true

export ROBOT_USER=<Your Robot User>
export ROBOT_PASSWORD=<Your Robot Password>
```

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

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

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

### Annotation and Environment Variable Reference Generation

The [Load Balancer annotation reference](docs/reference/load_balancer_annotations.md) and the [Load Balancer environment variable reference](docs/reference/load_balancer_envs.md) 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

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

## License

Apache License, Version 2.0

hcloud-cloud-controller-manager

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README