Configure a Hetzner load balancer

Hetzner load balancers in Syself Autopilot perform distinct roles depending on whether they serve platform infrastructure or application traffic. The control-plane load balancer sits in front of the Kubernetes API server and is managed through Cluster topology variables. Workload load balancers route public traffic directly to application pods and are configured through annotations on type: LoadBalancer Services. If you are deciding how to expose a specific workload, start with Choose how to expose an application .

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

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.

For the control plane, lb11 is sufficient for almost all deployments because standard control planes only maintain 3 to 5 nodes and rarely exceed 10,000 concurrent API connections. The same load balancer types and capacity thresholds apply to workload Services via the load-balancer.hetzner.cloud/type annotation. For up-to-date specifications and pricing, see Hetzner Load Balancers⁠.

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 Hetzner Cloud Controller Manager (CCM) automatically provisions a dedicated Hetzner Load Balancer whenever you create a Service with type: LoadBalancer. It registers cluster nodes as backend targets through an allocated NodePort and writes the assigned public IP addresses to 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.

Load balance to bare-metal nodes 

A Hetzner load balancer serves bare-metal (Robot) nodes like cloud nodes, so there is nothing extra to set up. The CCM adds the two kinds as different target types:

• Cloud nodes join as server targets, referenced by their server ID.
• Bare-metal nodes join as IP targets, by their public IPv4 address.

A pool can mix both, and the load balancer spreads traffic across them.

Bare-metal targets stay IPv4. The platform sets HCLOUD_LOAD_BALANCERS_ROBOT_TARGET_ADDRESS_FAMILY=ipv4 on the CCM, because nodes have no usable IPv6 and an IPv6 target would never pass its health check. Leave this default unchanged. The robot-target-address-family annotation sets it per Service.

With externalTrafficPolicy: Local, the load balancer only sends traffic to bare-metal servers that run a ready pod. Spread your pods across them, or run them as a DaemonSet, so no server sits idle. See Preserve the client source IP and Tune health checks for node replacement .

For why you would run bare metal, and how to add it, see Bare-metal nodes and Add bare-metal servers .

Where to go next 

• Tune health checks for node replacement
• Preserve the client source IP
• Serve IPv6 clients

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