Zurück zum Hub

cargo.ayedo.cloud/ayedo/k8s/hcloud-ccm 1.0.3 k8sapp Apache-2.0

Kubernetes Cloud Controller Manager for Hetzner Cloud — integrates nodes, routes, and load balancers with the Hetzner Cloud API

polycrate block pull cargo.ayedo.cloud/ayedo/k8s/hcloud-ccm:1.0.3

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.

Prerequisites

  • A Hetzner Cloud API token
  • Kubernetes nodes prepared for an external cloud provider (--cloud-provider=external). If Kubernetes was installed with the ayedo/linux/k8s block, set config.external_cloud_provider: true before 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 namespace
  • cluster_cidr (10.42.0.0/16) — Pod CIDR for CCM route controller (only when network.routes_enabled)
  • loadbalancer.location (fsn1) — Default LB location
  • loadbalancer.enabled (true) — Enable LB integration
  • network.enabled (true) — Enable Hetzner Cloud network integration
  • network.name ("") — Network name (defaults to workspace.name)
  • network.routes_enabled (true) — Manage Hetzner routes for node podCIDRs (--allocate-node-cidrs)
  • network.use_private_ip (true) — Use private IPs for LBs
  • network.disable_private_ingress (true) — Disable private ingress on LBs
  • network.disable_ipv6 (true) — Disable IPv6 on LBs
  • images.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-manager
  • ClusterRole/system:hcloud-cloud-controller-manager — Least-privilege RBAC
  • ClusterRoleBinding/system:hcloud-cloud-controller-manager:restricted
  • Deployment/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): Dedicated ClusterRole
  • 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:

  1. polycrate run ccm uninstall (with old block version — removes old RBAC resources)
  2. Update block to 1.0.0 (polycrate block pull cargo.ayedo.cloud/ayedo/k8s/hcloud-ccm)
  3. Replace config.version with config.images.ccm in workspace.poly
  4. polycrate run ccm install

Important: The old ClusterRoleBinding/system:cloud-controller-manager and ServiceAccount/cloud-controller-manager are not cleaned up automatically if you skip step 1. Remove them manually if needed.