DOCSEARCHbyAlgolia
Submit Docs

Hetzner Cloud Controller Manager (HCCM)

repository·main·Indexed 21 days ago

https://github.com/hetznercloud/hcloud-cloud-controller-manager

Integrates Kubernetes clusters with Hetzner Cloud and Robot APIs to manage resources such as Load Balancers and networking. It includes a Node Controller for node lifecycle management, a Service Controller for Load Balancers, and a Route Controller for native routing within Hetzner Cloud Private Networks.

Tokens
15.5K
Snippets
39
Records
78
Agent score
75%

What's inside hcloud-cloud-controller-manager

  1. Load Balancer guides overview

    main

    The hcloud-cloud-controller-manager provides a Load Balancer controller for managing Hetzner Cloud Load Balancers via Kubernetes. Documentation for specific tasks is organized into the following guides:

    • Quickstart: Get up and running quickly with a basic Load Balancer setup.
    • Configuration: Detailed information on how to configure the Load Balancer controller behavior.
    • Private Networks: Instructions for integrating Load Balancers with Hetzner Cloud Private Networks.

  3. How Hetzner Cloud Load Balancers work with Ingress and Gateway API

    main

    The hcloud-cloud-controller-manager (HCCM) does not act as an Ingress or Gateway API controller itself. Instead, it works in conjunction with them via the LoadBalancer service type.

    In a typical setup (e.g., using the NGINX Ingress Controller or NGINX Gateway Fabric), the workflow is:

    1. An Ingress or Gateway API resource is created.
    2. The specific Ingress/Gateway controller (like NGINX) watches this resource and configures its internal instance.
    3. To expose traffic, that controller creates a Kubernetes Service of type LoadBalancer.
    4. HCCM detects this LoadBalancer service and provisions a corresponding Hetzner Cloud Load Balancer to handle the external traffic.

    Note on L7 Routing: Hetzner Cloud Load Balancers currently do not support L7 routing. Consequently, HCCM does not include an Ingress controller or a Gateway API controller. If L7 capabilities are added to Hetzner Cloud Load Balancers in the future, a separate controller project may be developed.

  4. Understand and inspect Node Provider IDs

    main

    The spec.providerID in a Kubernetes Node object is a unique identifier that links the Kubernetes Node to its underlying Hetzner Cloud infrastructure. The Hetzner Cloud Controller Manager automatically sets this value during node initialization.

    Hetzner Provider ID Formats

    Depending on the infrastructure type, the ID follows these formats:

    • Hetzner Cloud Server: hcloud://<server-id>
    • Robot Server: hrobot://<robot-id>
    • Legacy Syself Robot Server: hcloud://bm-<robot-id> (Note: This format is maintained for backward compatibility and is not used for new nodes).

    To inspect the Provider IDs assigned to your nodes, use kubectl with custom columns.

    kubectl get nodes -o=custom-columns='Node Name:metadata.name,Provider ID:spec.providerID'

  5. How the hcloud-cloud-controller-manager controllers work

    main

    The hcloud-cloud-controller-manager (HCCM) is composed of multiple independent controllers following the standard Kubernetes cloud controller manager architecture.

    Key characteristics:

    • Independence: Controllers operate independently of one another.
    • Optionality: The Service Controller and Route Controller are not strictly required and can be disabled independently.
    • Dependency: The Route Controller requires specific CNI configuration to function correctly.

  6. How Robot server support works in the Node Controller

    main

    The Node Controller manages metadata for Robot servers, mapping Robot interface values to Kubernetes-standard labels and fields.

    Labels

    • node.kubernetes.io/instance-type: The server type (e.g., AX41, Server-Auction). Spaces are replaced with hyphens (-).
    • topology.kubernetes.io/region: The lowercase location (e.g., hel1, fsn1).
    • topology.kubernetes.io/zone: The lowercase location and datacenter (e.g., hel1-dc5, fsn1-dc16).
    • instance.hetzner.cloud/provided-by: Set to robot or cloud based on detection.

    Provider ID

    To identify the server after initial adoption, the controller sets Node.spec.providerID using the format hrobot://$SERVER_NUMBER. It also supports the legacy format hcloud://bm-$SERVER_NUMBER.

    Addresses

    The controller populates Node.status.addresses with the Hostname and available IPv4/IPv6 addresses.

    • IPv6: Uses the first address in the network (e.g., 2a01:f48:111:4221::1).
    • Private IPs: Automatic reporting of private IPs in a vSwitch is not supported.
    • Internal IPs: By default, InternalIPs configured via the kubelet flag --node-ip are passed through. You can disable this by setting the environment variable ROBOT_FORWARD_INTERNAL_IPS=false.

  8. Understand Load Balancer Target behavior changes

    main

    There is a change in how Load Balancer targets are managed when Robot support is disabled:

    • Syself Fork behavior: Robot Targets of the Load Balancer were left untouched if Robot support was not enabled.
    • hcloud-cloud-controller-manager behavior: The controller will actively remove any Robot Server targets from the Load Balancer if Robot support is not explicitly enabled.

  10. Handle changes to Provider ID format

    main

    The format of the Node Provider ID has changed to support Robot.

    • Old format: hcloud://bm-$SERVER_NUMBER
    • New format: hrobot://$SERVER_NUMBER

    While the controller still reads the old hcloud://bm- prefix for compatibility, all new nodes will be provisioned with the hrobot:// prefix. If your external tools or scripts parse the Provider ID, you must update your logic to handle the new hrobot:// format.

  11. How the Node Controller manages node lifecycle

    main

    The Node Controller tracks node status and provides metadata (such as the provider ID) to the cluster via the Hetzner Cloud API.

    To use the Node Controller, you must set the kubelet flag --cloud-provider=external. This configuration triggers two behaviors:

    1. Tainting: Nodes are automatically tainted with node.cloudprovider.kubernetes.io/uninitialized. This prevents workloads from being scheduled on a node until the HCCM has finished initializing it with cloud-specific information.
    2. Metadata Source: Kubernetes is instructed to ignore local metadata and instead use the Hetzner Cloud API to obtain node details.

  12. How Private Networks are used in HCCM

    main

    The hcloud-cloud-controller-manager (HCCM) leverages Hetzner Cloud Private Networks to provide two primary capabilities:

    1. Native Routing: It allows you to use the infrastructure's native routing capabilities in conjunction with your CNI (Container Network Interface). This eliminates the performance overhead associated with overlay networks like VXLAN.
    2. Private LoadBalancer Targets: It enables the use of private IP addresses as targets for LoadBalancers, ensuring traffic stays within the private network.

    When a Private Network is configured, HCCM automatically updates the corresponding Kubernetes Node object by adding the server's private IP address to the InternalIP field.