Configure a Hetzner load balancer

A Syself Autopilot cluster uses two kinds of Hetzner load balancers, and you configure them in two different places. The control-plane load balancer carries API server traffic and is set through topology variables on the Cluster object. Application load balancers carry your workload traffic and are set through annotations on each type: LoadBalancer Service. If you are still deciding whether a load balancer is the right way to expose an application, start with Choose how to expose an application .

flowchart LR
  A["kubectl and API clients"] --> CPLB["Control-plane LB :443"] --> API["Control-plane nodes :6443"]
  U["Internet clients"] --> APPLB["Per-Service LB"] --> NP["Node NodePort"] --> POD["Pods"]

The control-plane load balancer#

Syself Autopilot creates one Hetzner load balancer for the Kubernetes API server when it builds the cluster. It listens on port 443, forwards to port 6443 on the control-plane nodes, and carries only API traffic. The Hetzner CCM does not manage this one. The platform creates and reconciles it from your topology variables, so you configure it on the Cluster object, not with Service annotations.

		spec:
  topology:
    variables:
      - name: clusterLoadBalancerType
        value: lb21 # lb11 (default) | lb21 | lb31
      - name: clusterLoadBalancerName
        value: my-apiserver-lb # optional; Syself names it if you omit this
      - name: region
        value: nbg1 # fsn1 (default) | nbg1 | hel1 | ash | hil
	

clusterLoadBalancerType sets the Hetzner product. A load balancer type is defined by two limits: how many targets (the servers behind it) it can hold, and how many simultaneous connections it can carry.

Choose the smallest type that covers your control-plane node count and its peak connections; lb11 is sufficient for most clusters, since a control plane has few nodes. The same types and limits apply to the per-Service load balancers below through the type annotation. See the Hetzner load balancer page⁠ for the current numbers.

Changing the type on a running cluster resizes the load balancer in place, so it keeps its IP addresses. The region variable sets both the control plane's placement and the load balancer's region at once; the load balancer cannot live in a different region from the cluster.

Read the current settings from the HetznerCluster object:

		$ kubectl get hetznercluster <cluster-name> -o jsonpath='{.spec.controlPlaneLoadBalancer}'
	

The output shows enabled, algorithm, type, port, region, targetAddressFamily, enableProxyProtocol, and the healthCheck settings.

Application load balancers#

The CCM watches for Services with type: LoadBalancer. For each one it creates a Hetzner load balancer, connects your pods as targets through a NodePort, and writes the public address into status.loadBalancer.ingress.

		apiVersion: v1
kind: Service
metadata:
  name: my-app
  annotations:
    load-balancer.hetzner.cloud/location: fsn1
    load-balancer.hetzner.cloud/name: my-app-lb
spec:
  type: LoadBalancer
  selector:
    app: my-app
  ports:
    - port: 80
      targetPort: 8080
	

The CCM reconciles a Service whenever it changes, so most annotation edits take effect within seconds.

Defaults you get with no annotations#

The platform configures the CCM so a bare LoadBalancer Service already works:

• Dual-stack address. Every load balancer receives a public IPv4 and a public IPv6 address, and bridges IPv6 clients to the IPv4-only nodes. Disable IPv6 per Service with load-balancer.hetzner.cloud/ipv6-disabled: "true". See Serve IPv6 clients .
• Public-IP targeting. The load balancer reaches nodes over their public IP, because the platform runs no private network. You never set use-private-ip.
• Default region. A Service with no location receives a load balancer in the cluster's region. Set location regardless, so the region is explicit and does not drift from where your workload runs.

Annotation reference#

Every annotation goes on metadata.annotations of the Service.

Where to go next#

• Tune health checks for node replacement
• Preserve the client source IP
• Serve IPv6 clients
• Load balance to bare-metal nodes

For where load balancers sit in the wider networking picture, see Networking .