Hetzner Cloud Controller Manager
Installs the Kubernetes Cloud Controller Manager for Hetzner Cloud via static manifests. Integrates nodes, routes, and load balancers with the Hetzner Cloud API.
- Upstream — hetznercloud/hcloud-cloud-controller-manager
- License — Apache-2.0
- app_version — 1.30.1
- Kubernetes — >= 1.32 (tested: 1.33, 1.34, 1.35)
- Implementation — Static Kubernetes manifests (no Helm)
Prerequisites
- A Hetzner Cloud API token
- Kubernetes nodes prepared for an external cloud provider (
--cloud-provider=external). If Kubernetes was installed with theayedo/linux/k8sblock, setconfig.external_cloud_provider: truebefore provisioning nodes. - A Hetzner Cloud network (optional, controlled via
config.network.enabled)
A load balancer is only created in Hetzner Cloud once an Ingress controller (e.g.
ayedo/k8s/nginx) is installed.
Configuration
token("") — Hetzner Cloud API token (required)namespace(kube-system) — Target namespacecluster_cidr(10.42.0.0/16) — Pod CIDR for CCM route controller (only whennetwork.routes_enabled)loadbalancer.location(fsn1) — Default LB locationloadbalancer.enabled(true) — Enable LB integrationnetwork.enabled(true) — Enable Hetzner Cloud network integrationnetwork.name("") — Network name (defaults toworkspace.name)network.routes_enabled(true) — Manage Hetzner routes for node podCIDRs (--allocate-node-cidrs)network.use_private_ip(true) — Use private IPs for LBsnetwork.disable_private_ingress(true) — Disable private ingress on LBsnetwork.disable_ipv6(true) — Disable IPv6 on LBsimages.ccm(1.30.1) — CCM image version
Network
Set config.network.enabled: false to run the CCM without a Hetzner Cloud network. When disabled, HCLOUD_NETWORK, node CIDR allocation, and all network-dependent load balancer settings are omitted from the deployment.
Set config.network.routes_enabled: false when using an overlay CNI (e.g. Cilium VXLAN). Keeps HCLOUD_NETWORK for private-IP node matching and LB settings, but sets HCLOUD_NETWORK_ROUTES_ENABLED=false and omits --allocate-node-cidrs so CCM does not create/reconcile Hetzner routes from Kubernetes Node.spec.podCIDR (which often differs from Cilium cluster-pool CIDRs).
Actions
install
Deploys the CCM as a single-replica Deployment with tolerations for uninitialized and control-plane nodes, dedicated RBAC, and system-cluster-critical priority.
blocks:
- name: ccm
from: cargo.ayedo.cloud/ayedo/k8s/hcloud-ccm
kubeconfig:
from: k8s
config:
token: "HetznerCloudToken"
loadbalancer:
location: fsn1
enabled: true
network:
enabled: true
name: "" # defaults to workspace.name
routes_enabled: false # Cilium VXLAN / overlay CNI
use_private_ip: true
disable_private_ingress: true
disable_ipv6: true
uninstall
Removes the Hetzner Cloud Controller Manager from the cluster.
polycrate run ccm uninstall
Deployed Resources
Secret/hcloud— API token (and optional network name)ServiceAccount/hcloud-cloud-controller-managerClusterRole/system:hcloud-cloud-controller-manager— Least-privilege RBACClusterRoleBinding/system:hcloud-cloud-controller-manager:restrictedDeployment/hcloud-cloud-controller-manager— CCM with metrics on port 8233
Migration from < 1.0.0
This is a breaking change. Key differences:
- Config: image version — Old (< 1.0.0):
version: 1.15.0; New (1.0.0):images.ccm: "1.30.1" - RBAC — Old (< 1.0.0):
cluster-admin; New (1.0.0): DedicatedClusterRole - ServiceAccount — Old (< 1.0.0):
cloud-controller-manager; New (1.0.0):hcloud-cloud-controller-manager - ClusterRoleBinding — Old (< 1.0.0):
system:cloud-controller-manager; New (1.0.0):system:hcloud-cloud-controller-manager:restricted - Route reconciliation — Old (< 1.0.0): 30s polling; New (1.0.0): Watch-based (event-driven)
- Priority — Old (< 1.0.0): none; New (1.0.0):
system-cluster-critical - Metrics — Old (< 1.0.0): none; New (1.0.0): Port 8233
- Robot support — Old (< 1.0.0): none; New (1.0.0): Optional via Secret keys
Upgrade procedure:
polycrate run ccm uninstall(with old block version — removes old RBAC resources)- Update block to 1.0.0 (
polycrate block pull cargo.ayedo.cloud/ayedo/k8s/hcloud-ccm) - Replace
config.versionwithconfig.images.ccminworkspace.poly polycrate run ccm install
Important: The old
ClusterRoleBinding/system:cloud-controller-managerandServiceAccount/cloud-controller-managerare not cleaned up automatically if you skip step 1. Remove them manually if needed.