Skip to main content
Reference material for Hetzner clusters: every configuration parameter, datacenter location, and the details of the infrastructure Ankra provisions.

Cluster Configuration Options

The fields of POST /api/v1/clusters/hetzner. The portal’s create form sets most of them; see Create a Cluster. A server type you leave out is chosen from what the location can provision now: the cheapest available x86 type with at least 2 vCPU and 4 GB of memory for the bastion and workers, and at least 4 vCPU and 8 GB for the control plane and dedicated etcd nodes. Out-of-stock and deprecated types are skipped, and the response’s server_types object (bastion, control_plane, worker, etcd) names the type each provisioned role got. If the location has no such type, the create is refused with the list of types it does offer. A server type you name is checked against the location, and refused with the available types of at least that size when the location cannot provision it. The cx line is often unavailable, so check ankra cluster hetzner server-types --credential-id <id> --location <location> and name types from its AVAILABLE=yes rows, for example cpx12 for the bastion and cpx22 for the control plane and workers.

Hetzner Locations


Node Group API

Node Actions API

See Restart a node, Bastion and Change the control plane instance type for the dashboard and CLI equivalents.

SSH Key API

Disabled k3s Components API

The k3s_disabled_components list set at create can grow on a running k3s cluster. The body is the complete list and has to contain every entry already stored; an unknown or repeated entry is a 422 validation error pointing at the entry. applies answers: “The platform’s maintenance read lane compares each control plane’s k3s server config against this list within about five minutes and flags the ones missing an entry; the reconcile lane then patches the config and restarts k3s on one control plane at a time, in the cluster’s k8s update chain. Control planes already carrying every entry are not touched. The list only grows: re-enabling a bundled component is not supported yet, so a change that removes a stored entry is refused, and so is any change while a node update, version upgrade or node restart is still in progress on the cluster.” The refusals answer 409 with the detail shown:

Architecture

A Hetzner cluster provisions the following infrastructure: All nodes are deployed within a private Hetzner network and have no public IPs. The bastion host plays two roles:
  • SSH jump host - Ankra provisions and manages nodes through it, and it is the entry point for ssh -J access.
  • NAT gateway - a network route sends the nodes’ default traffic (0.0.0.0/0) to the bastion, which masquerades it out through its public IP. All node egress - image pulls, package installs, and the Ankra Agent’s outbound connection - flows through the bastion.
Because the bastion is the egress path on Hetzner, stopping or deleting it cuts off internet access for every node in the cluster. This differs from OVH clusters, where egress uses a provider-managed gateway and the bastion is only a jump host.
Inbound traffic to workloads does not pass through the bastion: LoadBalancer services get Hetzner Load Balancers from the CCM, attached to nodes over the private network.

Automatic Cloud Integration (hcloud Stack)

Ankra automatically deploys a hcloud stack during cluster provisioning. This stack includes:
  1. hcloud namespace - dedicated namespace for Hetzner cloud components
  2. hcloud-token secret - contains your Hetzner API token and network ID, sourced from the credential used to create the cluster
  3. hcloud-cloud-controller-manager - integrates the cluster with Hetzner Cloud APIs (node metadata, load balancers, node lifecycle)
  4. hcloud-csi - provides persistent storage using Hetzner Cloud Volumes
The hcloud stack is deployed automatically after the Ankra Agent is installed. The CCM and CSI charts both depend on the hcloud-token secret, and Ankra ensures the correct dependency order.
You do not need to manually set up the CCM or CSI driver - they are provisioned as part of cluster creation using the same Hetzner API credential you provided.

External Cloud Provider

With external_cloud_provider on (the default), every node’s kubelet runs with cloud-provider=external and its provider ID, so node initialisation is left to the Hetzner Cloud Controller Manager. This holds for both distributions. On a k3s cluster the servers also run with --disable-cloud-controller and the k3s service load balancer off, so the Hetzner CCM is the only cloud controller. When nodes first join the cluster, they carry a node.cloudprovider.kubernetes.io/uninitialized taint that prevents workload scheduling. The CCM removes this taint after initializing each node with its Hetzner provider ID, zone labels, and instance metadata. The Ankra Agent tolerates this taint so it can schedule immediately and begin managing the cluster before the CCM is fully running.

Hetzner Cloud Controller Manager (hcloud-ccm)

The Hetzner Cloud Controller Manager is automatically deployed as part of the hcloud stack and provides:
  • Node metadata - automatic zone, region, and instance type labels on nodes
  • Load Balancers - Kubernetes LoadBalancer services backed by Hetzner Cloud Load Balancers
  • Node lifecycle - automatic removal of deleted nodes from the cluster
Route management is off (HCLOUD_NETWORK_ROUTES_ENABLED: "false" below), so the CCM creates no pod routes in the Hetzner Cloud Network. The CCM is deployed in the hcloud namespace with 3 replicas and a PodDisruptionBudget. It reads the Hetzner API token from the hcloud-token secret that Ankra creates automatically.

CCM Configuration

The default CCM values configured by Ankra:
To customise the CCM configuration after creation, edit the hcloud-cloud-controller-manager add-on in the hcloud Stack, under Infrastructure → Clusters → <your cluster> → Stacks.
The CCM creates Hetzner Cloud Load Balancers when you create Kubernetes Service resources of type LoadBalancer. Terminating the cluster deletes them, together with any Load Balancer attached to the cluster’s network - see Hetzner specifics.

Hetzner CSI Driver (hcloud-csi)

The Hetzner CSI Driver is automatically deployed as part of the hcloud stack and provides:
  • Dynamic provisioning - create Hetzner Cloud Volumes on demand via PersistentVolumeClaim
  • Volume expansion - resize volumes without downtime
  • Storage classes - hcloud-volumes StorageClass available out of the box

CSI Configuration

The default CSI values configured by Ankra:
Once deployed, create PersistentVolumeClaims with storageClassName: hcloud-volumes:
The CSI driver creates Hetzner Cloud Volumes when you create PersistentVolumeClaims using the hcloud-volumes StorageClass. These Volumes are managed by Hetzner Cloud, not by Ankra. The default reclaimPolicy is Retain, meaning Hetzner Volumes are not deleted when PVCs are removed. Terminating the cluster lists the volumes its PersistentVolumes use and deletes them once you accept it; a volume labelled ankra-retain is kept - see Terminate a cluster.

Networking Stack

With include_networking on (the default), Ankra deploys a networking stack alongside the hcloud stack. It includes:
  1. Traefik - the Ingress controller (ingress class traefik, the cluster default) behind a Hetzner Cloud Load Balancer
  2. cert-manager - automated TLS certificate management
  3. Let’s Encrypt ClusterIssuer - a letsencrypt-prod ClusterIssuer configured for HTTP-01 validation through Traefik
With include_dns on (the default), the cluster also gets a delegated subdomain on ankra.cc and external-dns publishes Ingress hostnames into it.

Load Balancer Configuration

Traefik’s Service carries Hetzner Load Balancer annotations, and the balancer forwards over the private network with PROXY protocol so the client address reaches your workloads:
Traefik and cert-manager each run two replicas with a PodDisruptionBudget of one. These values are applied when the cluster is created; later changes you make to them are kept.

Using Ingress with TLS

Once the networking stack is deployed, create Ingress resources with automatic TLS:
Point your DNS record for app.example.com to the Hetzner Load Balancer IP that Traefik’s Service creates, or use a hostname under the cluster’s ankra.cc subdomain and let external-dns publish it. cert-manager handles the Let’s Encrypt certificate issuance and renewal.