HetznerCluster

In HetznerCluster you can define everything related to the general components of the cluster as well as those properties, which are valid cluster-wide.

There are two different modes for the cluster. A pure HCloud cluster and a cluster that uses Hetzner dedicated (bare metal) servers, either as control planes or as workers.

The HCloud cluster works with Kubeadm and supports private networks.

In a cluster that includes bare metal servers there are no private networks, as this feature has not yet been integrated in cluster-api-provider-hetzner. Apart from SSH, the node image has to support cloud-init, which we use to provision the bare metal machines.

Here you can find more information regarding the handling of SSH keys. Some of them are specified in HetznerCluster to have them cluster-wide, others are machine-scoped.

Usage without HCloud Load Balancer#

It is also possible not to use the cloud load balancer from Hetzner. This is useful for setups with only one control plane, or if you have your own cloud load balancer.

Using controlPlaneLoadBalancer.enabled=false prevents the creation of a hcloud load balancer. Then you need to configure controlPlaneEndpoint.port=6443 & controlPlaneEndpoint.host, which should be a domain that has A records configured pointing to the control plane IP for example.

If you are using your own load balancer, you need to point towards it and configure the load balancer to target the control planes of the cluster.

HTTP(S) health checks for the control plane load balancer#

By default the Hetzner load balancer checks the kube-apiserver service with a plain TCP check: it only verifies that the port accepts connections, not that the apiserver is actually ready to serve requests. Setting controlPlaneLoadBalancer.healthCheck.protocol to http or https switches the load balancer to request a path (e.g. /readyz) instead, so unhealthy control-plane nodes are taken out of rotation instead of continuing to receive traffic. Field names mirror the Hetzner Cloud API's load balancer health_check⁠ object.

This is opt-in and requires the kube-apiserver to serve the configured path without authentication, since the load balancer's health check request is unauthenticated. CAPH does not configure this for you; you must allow anonymous access to the configured path yourself, e.g. via kubeadm's default system:public-info-viewer RBAC binding or an AuthenticationConfiguration⁠ that scopes anonymous access to that path only. If this tradeoff isn't acceptable for your environment, leave healthCheck unset to keep the plain TCP check.

CAPH only sends the fields you set; a field you never set keeps Hetzner's own default — see the linked API reference above for the current defaults. path, domain, response and statusCodes are only valid when protocol is http or https. Use healthCheck.port when the health-check endpoint is served on a different port than the API server itself; left unset, the check runs against the service's own destination port.

Leaving healthCheck out entirely means CAPH does not manage the health check at all, so a load balancer you point CAPH at (or one that already has a check applied) keeps whatever check it has. That also means deleting healthCheck after an http check was applied does not undo it — to get a tcp check back, keep the field and set healthCheck.protocol: tcp.

Safe migration on an existing cluster#

If the load balancer switched to the http or https check immediately, every control-plane node running an older image that doesn't yet answer the configured path would be marked unhealthy at once, taking the API server offline. To avoid that, CAPH gates the switch the same way it gates enabling enableProxyProtocol: it waits until every control-plane infra machine carries the annotation capi.syself.com/http-health-check-for-controlplane-loadbalancer: "true" — set on the control-plane infra machine template — before switching the load balancer's health check in place. Until then the tcp check stays active and CAPH requeues.

This gate applies to every switch away from tcp, not only the first one. A new cluster whose spec already sets an http or https check is created with that check from the start (no annotation needed). The wait only covers the switch away from tcp: setting protocol back to tcp, and any change that stays within http/https (e.g. a new path, port or statusCodes), is applied on the next reconcile without waiting for the gate.

Overview of HetznerCluster.Spec#