Prerequisites
Before creating an OVH cluster, you need two credentials:OVH API Credential
OVH Cloud API credentials (application key, application secret, consumer key, and project ID). See OVH API Credentials.
SSH Key Credential
An SSH public key for server access. You can provide your own or let Ankra generate one. See SSH Key Credentials.
Creating an OVH Cluster
Via the Platform UI
A guided wizard walks you through creating an OVH cluster - select credentials, pick a region, choose instance flavors (general purpose, CPU-optimized, or RAM-optimized), set control plane and worker counts, and launch.1
Navigate to Clusters
Go to Clusters in the Ankra dashboard and click Create Cluster.
2
Select OVH Cloud
Choose OVH Cloud as the provider.
3
Select Credentials
Pick your OVH API credential and SSH key credential from the dropdowns. You can also create new credentials directly from the wizard.
4
Choose Region
Select an OVH Cloud region (e.g., Gravelines, Strasbourg, Beauharnois, Warsaw, London, Frankfurt). Each region shows the location and country.
5
Configure Nodes
Set your cluster topology:
- Bastion - instance flavor for the SSH bastion (e.g.,
b2-7) - Control Plane - count and flavor (e.g., 1x
b2-15) - Workers - count and flavor (e.g., 2x
b2-15)
6
Create & Track Progress
Click Create to start provisioning. A live progress view tracks every step - network creation, bastion setup, control plane provisioning, worker provisioning, Kubernetes installation (kubeadm or k3s), and Ankra Agent setup. The cluster appears with an offline state until provisioning completes, then transitions to online.
Managing from the Dashboard
Once your OVH cluster is online, you can manage it directly from the Ankra dashboard:- Scale workers - go to Cluster Settings → General to scale worker nodes up or down
- Upgrade Kubernetes - upgrade the Kubernetes version from cluster settings
- Deprovision - delete the cluster and all OVH resources from the Danger Zone in cluster settings
Via the CLI
Via the API
Availability Zones
Some OVH regions are 3-AZ: one region spanning three availability zones with independent power, cooling, and networking.EU-WEST-PAR holds eu-west-par-a, eu-west-par-b and eu-west-par-c, and EU-SOUTH-MIL holds the equivalent three. Every other region is a single failure domain, so check before you plan around zones.
Two rules come from OVH and shape everything below. An instance’s zone is chosen at creation, and a request that names no zone gets whichever zone OVH picks - in practice the same one for every node of a cluster. And an instance’s zone is fixed for its lifetime, so re-placing a node means replacing it.
Find the zones a region has
Zone names are region-scoped, so check the spelling before you use one. Only a region whose type isregion-3-az accepts zone placement.
Spread a new cluster across zones
Pass the zone pool at create. Ankra distributes instances across it deterministically: control planes and etcd spread per role, workers spread per node group, so a three-node database group gets one node in each zone rather than being balanced against unrelated workers.Pin a node group to one zone
A node group can be pinned to a single zone instead of spreading. Pin the group that runs zonal storage, because an OVH volume cannot attach from another zone.Node topology labels
Every OVH node carries the standard Kubernetes topology pair, so zone-aware scheduling works without extra configuration:
The zone comes from what OVH reports for the live instance rather than what was requested, so it is correct even on clusters created before zone placement existed.
On those older clusters Ankra records the zone automatically the next time it reads the instance, but the labels are written by a server sync. Trigger one rather than waiting for it:
Fixing a cluster that is already in one zone
- Workers - in place. Add a node group pinned to the target zone, drain the old group, then delete it. No cluster rebuild.
- Control planes - not in place. The zone is immutable, Ankra never re-places an existing control plane, and a control plane count change is stopped-cluster-only. A zone-spread control plane on an existing cluster means recreating the cluster.
Zone tolerance needs more than node spread
OVH High Speed block storage is zonal. It is triple-replicated within a single zone and cannot attach from another. A single database pod with a single PersistentVolume is therefore not zone-fault-tolerant however the nodes are spread: the volume is the single-zone dependency, and if its zone goes down the pod cannot start anywhere else. A zone-fault-tolerant stateful workload needs all of:- Replication at the application layer - CloudNativePG or Patroni with one replica per zone, each with its own volume. Node spread gives the replicas somewhere to live; it does not create them.
-
A
WaitForFirstConsumerStorageClass so the volume is provisioned in the zone the pod was actually scheduled to, rather than binding first and stranding the pod. Ankra shipscsi-cinder-sc-topologyfor exactly this reason, and marks it the default on new OVH clusters. On a cluster created earlier, k3s’slocal-pathclass is still present and also marked default, so name the class explicitly on anything that matters rather than relying on which default wins: -
allowedTopologieson the StorageClass, or a zone-pinned node group per replica, so a rescheduled pod cannot land where its volume is not. -
topologySpreadConstraintskeyed ontopology.kubernetes.io/zonefor the stateless tiers.
Node Groups
Node groups let you organize worker nodes into logical groups with independent instance flavors, counts, labels, and taints. Each group can be scaled, re-flavored, and configured independently.Via the Platform UI
Navigate to cluster Settings > Nodes to manage node groups. From this tab you can:- View all node groups with their instance flavor, count, labels, and taints
- Add new node groups with a name, instance flavor, count, and optional labels/taints
- Scale individual groups up or down (0–100 nodes)
- Upgrade the instance flavor (upgrade only - see Instance Flavor Changes)
- Edit labels and taints per group
- Delete a node group and all its nodes
List Node Groups
Add a Node Group
From the CLI, a node group can be created with its Kubernetes labels and taints in one step:Scale a Node Group
Instance Flavor Changes
Update Labels and Taints
--clear (or an empty value via the API) removes them, and a taint effect defaults to NoSchedule.
Delete a Node Group
Node Group API Reference
All node-group operations are also available via the REST API - see the OVH Node Group API.Legacy Worker Scaling
The legacyscale-workers and worker-count endpoints still work for backward compatibility.
For new clusters, prefer using Node Groups for more granular control.
Upgrading Kubernetes Version
You can upgrade the Kubernetes (k3s) version on all nodes in an OVH cluster. Upgrades are applied to control plane nodes first, then workers.Via the Dashboard
Go to your cluster → Settings → General to see the current k3s version and trigger an upgrade.Check Current Version
Upgrade Version
Stopping and Starting a Cluster
You can stop an OVH cluster to release its compute (node instances, the bastion, and the managed network gateway) while keeping its configuration, networking definition, and SSH keys. Starting the cluster re-provisions the compute and reconciles it back to a running state. This is useful for pausing non-production clusters to save cost. When starting, use--scope control_plane to bring up only the control plane first (for example to inspect or repair it), or --scope all (the default) to provision the whole cluster.
Stop and start are background operations. A start returns
409 if a stop or terminate operation is still running. The private network is preserved while stopped and reused on the next start.--force (or ?force=true on the API) to delete them together with any load balancers the cluster created. Ankra deletes exactly the volumes it recorded for this cluster, never other volumes in the project.
SSH Access and Keys
ankra cluster ovh access-info prints the bastion and control plane IPs along with ready-to-paste ssh -J jump and Kubernetes API port-forward commands, so you can reach nodes behind the bastion without looking up IPs by hand.
Managing the Control Plane
Inspect the control plane configuration, then change the node count or instance flavor. OVH control planes support a count of1 or 3.
Inspecting Nodes
List every node in the cluster or fetch the details of a single node by ID. The list includes each node’s live status as last reported by the OVH API (provider_status / provider_power_state) - useful for spotting a crashed or unexpectedly powered-off instance before you restart it.
Restarting a Node
Restart any individual node - a control plane node, a worker, or the bastion/gateway - without waiting for a full reconciliation. Ankra schedules the restart as a tracked operation via the OVH API: a running instance gets a soft reboot (falling back to a hard reboot if the guest OS doesn’t respond), and aSHUTOFF instance is started instead.
Via the Platform UI
Open cluster Settings > Nodes, find the node in the table, and choose Restart from its row menu. Confirm the dialog to schedule the restart.Via the CLI or API
Find the node’s ID withnodes list, then restart it:
The node must be in the
up state with no restart already in flight. Track the restart with the returned operation_id via ankra cluster operations list <operation_id> or the CLI reference. Workloads on the node are briefly unavailable while it reboots.Resizing the Bastion or Gateway
Change the bastion/gateway’s instance flavor without recreating the cluster. Ankra powers it off, resizes it, and powers it back on - causing a brief SSH and outbound-NAT interruption.Like node-group writes, this endpoint answers
202 Accepted and applies the resize in the background unless you pass --wait (CLI) or ?wait=true (API).Deprovisioning
Deprovisioning deletes all OVH resources (instances, networks, SSH keys) and removes the cluster from Ankra.Via the Dashboard
Go to your cluster → Settings → General → Danger Zone and click Deprovision Cluster. You will be asked to confirm before the operation begins.Via CLI or API
--force deletes them along with the rest of the infrastructure, tolerates unreachable cluster infrastructure, and works on a cluster that was stopped earlier: the volumes recorded at stop time are still known and get reclaimed.
Architecture
An OVH cluster provisions the following infrastructure:
All nodes are deployed within a private OVH network and have no public IPs. Two different components share the word “gateway”, so it helps to keep them apart:
- The managed network gateway (created alongside the private network, named
<cluster>-network-gw) is the actual router: every node’s default route points at it, and all outbound traffic to the internet leaves through it. - The bastion (named
<cluster>-bastion) is an SSH jump host, not a router. No workload or egress traffic flows through it. Ankra connects to its public IP to provision nodes, install Kubernetes, apply upgrades, and run reconciliation, and you can use it forssh -Jaccess to the nodes.
Clusters created before the bastion rename carry the instance name
<cluster>-gateway in OVH instead of <cluster>-bastion. It is the same component with the same role; existing clusters keep their original instance name.Troubleshooting
Common Issues
OVH Cloud Quotas
OVH Cloud has default resource limits per project. If provisioning fails, check your quotas in the OVH Control Panel:- Instances
- Networks / VLANs
- SSH Keys