Create an UpCloud cluster

Creates an UpCloud cluster from the request and starts provisioning it in the background, answering 201 with the new cluster’s cluster_id and name. A configuration that fails validation answers 400 with the reason, and an organisation whose billing is restricted is refused with 402.

POST /api/v1/clusters/upcloud

Create an UpCloud cluster

Python

import requests

url = "https://platform.ankra.app/api/v1/clusters/upcloud"

payload = {
    "credential_id": "<string>",
    "name": "<string>",
    "ssh_key_credential_id": "<string>",
    "zone": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

201

{
  "cluster_id": "<string>",
  "name": "<string>"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

authorization · string | null

x-ankra-organisation-id · string | null

Body

application/json

credential_id · string<uuid4> · required

name · string · required

ssh_key_credential_id · string<uuid4> · required

zone · string · required

bastion_allowed_ips · string[]

IPv4 addresses or CIDRs allowed to reach the bastion's SSH port. The platform's own egress addresses are always allowed in addition, so the platform can never be locked out. Omit (or send an empty list) to keep the bastion reachable from anywhere (key-only SSH, rate-limited). IPv6 and 0.0.0.0/0 entries are refused; at most 64 entries.

Maximum array length: 64

bastion_plan · string · default: 1xCPU-1GB

cni · enum<string>

Container network. Omitted resolves to cilium on kubeadm (the default distribution) and flannel on k3s.

Available options: flannel, calico, cilium

control_plane_count · integer · default: 1

control_plane_plan · string · default: 2xCPU-4GB

criticality · enum<string> | null

Available options: production, staging, development, disposable

description · string | null

distribution · string · default: kubeadm

environment · string | null

Required string length: 1 - 50

etcd_node_count · integer · default: 3

etcd_plan · string · default: 2xCPU-4GB

etcd_topology · string · default: stacked

external_cloud_provider · boolean · default: true

gateway_plan · string · default: standard

UpCloud NAT gateway plan every node's outbound internet runs through, from GET /api/v1/clusters/upcloud/gateway-plans. Omitted is 'standard', the cheapest plan on two servers: a one-server plan ('development', 'essentials') loses all cluster egress while UpCloud rebuilds it. An unlisted plan answers 400.

gitops_branch · string · default: master

gitops_credential_name · string | null

gitops_repository · string | null

gitops_provider · enum<string> · default: github

GitOps provider of the repository the cluster is bootstrapped onto. Omitted is github, where gitops_repository is owner/name. bitbucket_cloud names the repository by gitops_workspace and gitops_repo_slug (or gitops_repository as workspace/repo_slug) and binds it as a Bitbucket Cloud repository.

Available options: github, bitbucket_cloud

gitops_workspace · string | null

Bitbucket Cloud workspace of the GitOps repository. Only with gitops_provider bitbucket_cloud; provided together with gitops_repo_slug.

gitops_repo_slug · string | null

Bitbucket Cloud repository slug of the GitOps repository. Only with gitops_provider bitbucket_cloud; provided together with gitops_workspace.

include_networking · boolean · default: true

gateway_api · boolean · default: false

Install the Kubernetes Gateway API beside Traefik's Ingress: the Gateway API standard CRDs, Traefik's Gateway provider with the traefik GatewayClass and a shared traefik-gateway Gateway in the traefik namespace (a plain HTTP listener that accepts routes from every namespace), cert-manager's Gateway support, and external-dns publishing of HTTPRoute hostnames. Ingress keeps working; one Traefik serves both. Requires include_networking.

kubernetes_version · string | null

k3s_disabled_components · enum<string>[] | null

k3s packaged components to keep disabled (k3s --disable), for example ["traefik"] on a cluster that brings its own ingress. k3s distribution only: the list is rendered into the server config at install and re-asserted by the maintenance pass, so the entries stay off across restarts.

Available options: coredns, servicelb, traefik, local-storage, metrics-server, runtimes

load_balancer_plan · string | null

UpCloud plan of the ingress load balancer (see GET /api/v1/clusters/upcloud/load-balancer-plans). Omitted, it is production-small (two nodes) for a cluster whose criticality is production and development (one node) otherwise. Only meaningful with include_networking.

network_mode · enum<string>

Derived when omitted: wireguard_mesh for a multi-zone pool, private_network otherwise. Set wireguard_mesh on a single-zone cluster to make it mesh-capable so zones can be added later; a mesh cannot be retrofitted.

Available options: private_network, wireguard_mesh

network_ip_range · string | null

node_groups · CreateUpcloudNodeGroupRequest · object[] | null

Show child attributes

worker_count · integer · default: 1

worker_plan · string · default: 2xCPU-4GB

zones · string[]

Zone pool for a multi-zone cluster. Must contain zone (the primary zone: bastion, first control plane and default network). Each additional zone gets its own SDN router, private network and NAT gateway, and the nodes are joined by a platform-managed WireGuard mesh. More than one zone needs at least three zones and three control planes. Omitted keeps the cluster in zone only.

Response

201

application/json

Cluster created successfully

cluster_id · string<uuid4> · required

name · string · required