Before you start
- A payment method on the organisation. Without one, the create is refused with “Add a payment method to create this cluster.” See Credit and payment method.
- An UpCloud API token with permission to manage servers, networking, storage and Kubernetes, stored as an UpCloud credential: Integrations & alerts → Credentials → Add credential → UpCloud, or Add a credential inside the create form.
- An SSH key credential - your own public key, or one Ankra generates. See SSH Key Credentials.
- Room in your account’s limits for the servers, networks, routers and IP addresses. Check them in the UpCloud Control Panel; UpCloud support raises them.
Create the cluster
- Portal
- CLI
- API
Follow Create a Cluster with these UpCloud choices:
1
Choose UpCloud
Go to Infrastructure → Clusters, click Add a cluster, pick UpCloud, then Ankra managed under Who runs Kubernetes on UpCloud? (Provider managed creates an UpCloud UKS cluster).The form Add an UpCloud cluster opens.
2
Where it runs
Choose the UpCloud credential, the SSH key and the Zone. Then pick the two network plans, read live from your UpCloud account; see NAT gateway and load balancer plans:
- NAT gateway (outbound internet) - the gateway every node reaches the internet through. Choose it now: changing it later cuts the cluster’s internet access for several minutes.
- Ingress load balancer (incoming traffic) - the load balancer in front of the ingress Ankra installs. It starts on
development(one node), orproduction-small(two nodes) when the cluster runs Production. It is offered only with Install the networking stack.
3
Control plane and servers
Pick Single node or High availability, the Control plane size, and the Management server size. Each size field lists the zone’s plans under Exact server type. The form starts with
PREMIUM-4xCPU-8GB for the control plane and workers.4
Worker nodes
The form creates one node group; add more once the cluster is running. Under Placement, labels and taints, Pin to availability zone keeps the group in one zone of a multi-zone pool.
5
Zones (optional)
Under Advanced configuration → UpCloud zone placement, tick Spread nodes across zones and choose at least three zones, including the one you picked above. This switches the form to kubeadm and three control plane nodes. For a single-zone cluster that may grow later, tick Enable WireGuard mesh so zones can be added later instead. See Multi-zone clusters.
6
Review and create
Click Review cluster, check the settings and the cost, then click Create cluster. The progress page follows the stages to <cluster name> is ready.
Verify
- In Infrastructure → Clusters, the cluster’s status moves from In progress to Online once the Ankra Agent has connected.
-
Point
kubectlat it through Ankra (this needs a Cluster Access grant) and check the nodes:Every control plane and worker should beReady. See Accessing Clusters with kubectl.
What Ankra created in your account
- An SDN router and a private network with DHCP handing out the default route. Nodes have no public interface.
- A managed NAT gateway on the router - the egress path for all node traffic.
- A bastion - the only server with a public IP. It is an SSH jump host only: Ankra reaches the nodes through it to provision, upgrade and reconcile, and no workload or egress traffic flows through it.
- Control plane and worker servers, and your SSH key on every server.
- The upcloud-cloud-provider stack - the UpCloud cloud controller manager and CSI driver, for
LoadBalancerServices and persistent storage, using your credential.
NAT gateway and load balancer plans
Two UpCloud resources in front of the cluster are billed to your account by plan:- The NAT gateway carries all outbound traffic: image pulls, the Ankra agent’s connection, and any outside service your applications call. A plan that runs on two or more servers keeps egress up while UpCloud replaces one. Without a choice, a new cluster gets
standard, the cheapest two-server plan. - The ingress load balancer carries incoming traffic to the ingress Ankra installs with the networking stack.
developmentruns one load balancer node; theproduction-*plans run two. Without a choice, a production cluster getsproduction-smalland every other clusterdevelopment.
- Portal
- CLI
Go to Infrastructure → Clusters → <your cluster> → Settings → Network. Under Internet gateway and load balancer:
- Change NAT gateway plan - pick the plan, tick “I understand this cluster will have no outbound internet access for several minutes.” and click Change NAT gateway plan.
- Change load balancer plan - pick the plan and click Change load balancer plan. UpCloud moves the existing load balancer onto the new plan in place.
UpCloud specifics
- Plan changes go one way. A node group moves to a larger plan only; 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.
- SSH allowlist. At create time, Addresses allowed to reach the management server under Advanced configuration (or
--bastion-allowed-ips) limits SSH to the bastion to the IPv4 addresses or ranges you list; empty allows any address. On a running cluster, replace the list withankra cluster upcloud bastion allowed-ips my-cluster 203.0.113.7 198.51.100.0/24, or remove it with--clear. - Stop. A stop releases the node servers, the bastion and the NAT gateway, and keeps the networking definition and SSH keys. The CSI storage volumes are kept and billed while the cluster is stopped.
- Terminate deletes the servers, networks, routers, gateways and SSH keys. The storage volumes Ankra deletes, once you accept it, are exactly the ones it recorded for this cluster - never other disks in the account.
Multi-zone clusters
UpCloud has no multi-zone region: every private SDN network, router and managed load balancer lives in one zone, so a cluster is single-zone by construction. Ankra can stretch a cluster across a zone pool instead - one private network and NAT gateway per zone, the nodes joined by a platform-managed kernel WireGuard mesh over UpCloud’s account-wide utility network, and Kubernetes advertising the overlay address on every node. Losing a zone then costs capacity, not the cluster.Multi-zone placement needs the
kubeadm distribution (the default).network_mode: wireguard_mesh.
Create a cluster across zones
zone stays the primary zone - bastion, first control plane and default network - and must be in zones. Control planes spread one per zone; workers spread per node group unless a group is pinned.
network_mode is derived - wireguard_mesh for a pool, private_network otherwise - and can be set to wireguard_mesh on a single-zone cluster to make it mesh-capable:
Grow the pool
Zones can be added to awireguard_mesh cluster, never removed. Pass the full desired pool, primary zone first; every new zone gets its router, private network and NAT gateway, and later node groups spread across the grown pool.
Pin a node group to one zone
Pin the group that runs zonal storage: an UpCloud volume cannot attach from another zone.ankra cluster node-group list ends each line with zones= and the zones the group’s nodes were placed in (zones on the node-group listing API).
Node topology labels
Every node carriestopology.kubernetes.io/zone (the UpCloud zone, e.g. fi-hel2) and topology.kubernetes.io/region (the zone without its index, e.g. fi-hel), so topologySpreadConstraints and zone-aware scheduling work without extra configuration.
Node addressing on a meshed cluster
Every node advertises its overlay address to Kubernetes, so that is whatkubectl get nodes -o wide reports as INTERNAL-IP - not the node’s private SDN address. Overlay addresses are allocated per cluster from a range Ankra manages (172.30.0.0/16 by default) and stay stable for the life of a node, so anything keyed on a node IP - monitoring targets, NO_PROXY lists, allow-lists - should use the overlay address:
/24 from the cluster’s private range. A range Ankra picks for you differs from cluster to cluster, so pick network_ip_range yourself, with room for every zone you expect to add.
LoadBalancer Services on a meshed cluster
A meshed cluster advertises each node’s overlay address as its Kubernetes InternalIP. An UpCloud load balancer is not part of the WireGuard mesh, so a backend registered at that address would be unreachable.
Ankra runs a cloud controller manager on meshed clusters that takes each backend member’s address from the node’s address on the private network the load balancer is attached to, rather than from the InternalIP. That is the one address a load balancer can always reach, so LoadBalancer Services - including the Traefik ingress the networking stack installs - work normally. You do not need to configure anything.
This is worth knowing if you compare a meshed cluster against a stock UpCloud CCM: the address behaviour is a deliberate difference, and the controller runs with its node controller disabled, because the overlay address it would otherwise reject is the whole point of a meshed cluster. Ankra applies the
topology.kubernetes.io/* and node.kubernetes.io/instance-type labels itself instead.What stays in the primary zone
UpCloud block storage is zone-local, and the cluster’s CSI is scoped to the primary zone:PersistentVolumeClaims are provisioned in the primary zone. Run stateful workloads there, or use replicated storage such as Longhorn for the other zones.- The bastion is in the primary zone: if that zone is lost, workloads keep running in the others, but provisioning and node management pause until it returns.
- The cloud controller manager cannot match a node’s overlay address to an address UpCloud reports for the server, so it does not maintain node addresses on a meshed cluster. Ankra runs the CCM with its node controller disabled there and stamps the
topology.kubernetes.io/*andnode.kubernetes.io/instance-typelabels itself; nodes register, stayReadyand keep theirproviderID.
Operate it
Day-2 tasks work the same way on every Ankra Managed provider, with the CLI nameupcloud:
- 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