Hetzner Clusters

​

Before you start

• A Hetzner Cloud API token with read and write permissions, stored as a Hetzner credential. No Hetzner account yet? Sign up for Hetzner Cloud.
• One or more SSH key credentials - your own public key, or one Ankra generates. See SSH Key Credentials.
• Room in your Hetzner project’s limits for the servers, a network and the SSH keys. Check them in the Hetzner Console; Hetzner support raises them.

​

Create the cluster

ankra credentials hetzner create --name my-hetzner-token   # prompts for the token
ankra credentials hetzner ssh-key create --name my-ssh-key --generate

ankra cluster hetzner create \
  --name my-cluster \
  --credential-id <hetzner-credential-id> \
  --ssh-key-credential-ids <key-id-1>,<key-id-2> \
  --location fsn1 \
  --control-plane-count 1 \
  --worker-count 2

curl -X POST https://platform.ankra.app/api/v1/clusters/hetzner \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-cluster",
    "credential_id": "<hetzner-credential-id>",
    "ssh_key_credential_ids": ["<key-id-1>", "<key-id-2>"],
    "location": "fsn1",
    "control_plane_count": 1,
    "control_plane_server_type": "cpx32",
    "node_groups": [
      {"name": "default", "instance_type": "cpx32", "count": 2},
      {"name": "gpu-workers", "instance_type": "ccx33", "count": 1, "labels": {"gpu": "true"}, "taints": [{"key": "gpu", "value": "true", "effect": "NoSchedule"}]}
    ],
    "include_networking": true,
    "include_dns": true,
    "gitops_credential_name": "my-github-token",
    "gitops_repository": "my-org/my-repo",
    "gitops_branch": "main"
  }'

​

Verify

1. The cluster moves from Provisioning to Online in the clusters list once the Ankra Agent has connected.
2. Point kubectl at it through Ankra (this needs a Cluster Access grant) and check the nodes:
   ankra cluster kubeconfig add my-cluster --use
   kubectl get nodes
   
   Every control plane and worker should be Ready. See Accessing Clusters with kubectl.

​

What Ankra created in your project

• A private network that every server joins. Nodes have private addresses only.
• A bastion - the only server with a public IP. It is the SSH jump host and also the NAT gateway for all node egress, so stopping or deleting it cuts the nodes off from the internet.
• Control plane and worker servers, and your SSH keys registered in the project.
• The hcloud stack in the hcloud namespace: the Hetzner cloud controller manager (Load Balancers for LoadBalancer Services, node metadata) and the CSI driver (Hetzner Volumes through the hcloud-volumes StorageClass), both using your credential’s token.

​

Server types

• Leave a server type out and Ankra picks it when the cluster is created, from what the location can provision at that moment: the cheapest x86 type with at least 2 vCPU and 4 GB 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. The create response and the AI’s create result name the type each role got.
• Name a type and Ankra checks it against the location first. If the location cannot provision it, the create is refused with the types of at least that size it can provision instead, cheapest first.
• For a node group that autoscales, pick a type the location sells reliably. Each scale-up orders a new server of the group’s type, so a group on a type that goes out of stock cannot grow until it is back.

​

Hetzner specifics

• Disk growth is irreversible. Moving a node group to a larger server type enlarges each server’s disk, which Hetzner cannot shrink, so a group can never move back to a smaller type. Each node is powered off, resized and powered on, with brief downtime for its workloads. For smaller nodes, create a new group and delete the old one.
• Restart is a native reboot, falling back to a power cycle when the server does not respond.
• SSH keys are shared by fingerprint. Hetzner registers a public key once per project, so a key used on several Ankra Hetzner clusters is one Hetzner key object, and terminating any of those clusters deletes it. Running nodes keep working (their authorized_keys are already written), and the next key sync registers it again.
• What a terminate touches. Servers, the network and SSH keys are deleted by the IDs Ankra recorded - Ankra never lists your project and deletes what it finds. Just before the network is deleted, three scoped sweeps run: servers carrying this cluster’s ankra-cluster-id label and attached to its network, volumes carrying that label, and Load Balancers attached to its network or carrying that label. That last filter is a union, so a Load Balancer you attached to the cluster’s network by hand is removed too. Load Balancers are deleted on every terminate, because an attached one blocks the network delete. Your Hetzner API token is never touched.
• Keeping a volume. A Hetzner Volume labelled ankra-retain is kept when the cluster is terminated.

​

Operate it

• Node groups and legacy worker scaling
• Control plane
• Restart a node and the bastion
• SSH access and keys
• Upgrade Kubernetes
• Stop and start
• Terminate a cluster

​

Troubleshooting