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 ready to serve requests. Setting controlPlaneLoadBalancer.healthCheck.protocol to http or https makes the load balancer request a path (for example /readyz) instead, so a control plane that is not ready is taken out of rotation instead of receiving traffic. The field names and their limits mirror the Hetzner Cloud API's load balancer health_check object⁠.

The endpoint the check requests must answer without authentication, because the load balancer cannot present credentials. CAPH does not configure that for you. Use healthCheck.port when that endpoint is served on a different port than the API server itself.

CAPH sends only the fields you set. A field you never set keeps the default Hetzner applies for it, see the linked API reference above for the current defaults. Leaving healthCheck out means CAPH does not manage the health check, so a load balancer you point CAPH at keeps the check it already 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. path, domain, response and statusCodes are only valid when protocol is http or https.

Safe migration on an existing cluster 

If the load balancer switched to the http check right away, every control plane still running an older image that does not answer the path would be marked unhealthy at once, taking the API server offline. So CAPH waits, the same way it does for enableProxyProtocol: it switches the check only once 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. Until then the tcp check stays active and CAPH requeues.

This applies to every switch from tcp to http or https, 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.

The wait only covers the switch away from tcp. Setting protocol back to tcp is applied on the next reconcile, and so is a change that stays within http or https, for example a new path, port or statusCodes.

Overview of HetznerCluster.Spec