Cluster Configuration Options
The fields ofPOST /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 -Jaccess. - 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.
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:hcloudnamespace - dedicated namespace for Hetzner cloud componentshcloud-tokensecret - contains your Hetzner API token and network ID, sourced from the credential used to create the cluster- hcloud-cloud-controller-manager - integrates the cluster with Hetzner Cloud APIs (node metadata, load balancers, node lifecycle)
- hcloud-csi - provides persistent storage using Hetzner Cloud Volumes
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
Withexternal_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
LoadBalancerservices backed by Hetzner Cloud Load Balancers - Node lifecycle - automatic removal of deleted nodes from the cluster
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: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-volumesStorageClass available out of the box
CSI Configuration
The default CSI values configured by Ankra: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
Withinclude_networking on (the default), Ankra deploys a networking stack alongside the hcloud stack. It includes:
- Traefik - the Ingress controller (ingress class
traefik, the cluster default) behind a Hetzner Cloud Load Balancer - cert-manager - automated TLS certificate management
- Let’s Encrypt ClusterIssuer - a
letsencrypt-prodClusterIssuer configured for HTTP-01 validation through Traefik
include_dns on (the default), the cluster also gets a delegated subdomain on ankra.cc and external-dns publishes Ingress hostnames into it.