Create a Proxmox VE cluster

import requests

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

payload = {
    "name": "<string>",
    "credential_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "ssh_key_credential_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "node": "<string>",
    "bridge": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    credential_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    ssh_key_credential_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    node: '<string>',
    bridge: '<string>'
  })
};

fetch('https://platform.ankra.app/api/v1/clusters/proxmox', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://platform.ankra.app/api/v1/clusters/proxmox \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "credential_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "ssh_key_credential_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "node": "<string>",
  "bridge": "<string>"
}
'

{
  "cluster_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>"
}

{
  "detail": "Cluster not found"
}

{
  "detail": "Cluster not found"
}

{
  "detail": "Cluster not found"
}

{
  "detail": "Cluster not found"
}

{
  "detail": "Cluster not found"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

{
  "detail": "Cluster not found"
}

Proxmox Clusters

Create a Proxmox VE cluster

Creates a self-managed kubeadm or k3s cluster on Proxmox VE VMs from the request and starts provisioning it in the background, answering 201 with the new cluster’s cluster_id and name. The VMs are cloned on the chosen node (or spread across placement_nodes) and attached to the chosen bridge. An option the provider does not support (such as external_cloud_provider) or a configuration that fails validation answers 400 with the reason, a full network identity pool answers 409, and an organisation whose billing is restricted is refused with 402. Requires clusters.create.

POST

api

clusters

proxmox

Create a Proxmox VE cluster

import requests

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

payload = {
    "name": "<string>",
    "credential_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "ssh_key_credential_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "node": "<string>",
    "bridge": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    credential_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    ssh_key_credential_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    node: '<string>',
    bridge: '<string>'
  })
};

fetch('https://platform.ankra.app/api/v1/clusters/proxmox', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://platform.ankra.app/api/v1/clusters/proxmox \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "credential_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "ssh_key_credential_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "node": "<string>",
  "bridge": "<string>"
}
'

{
  "cluster_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>"
}

{
  "detail": "Cluster not found"
}

{
  "detail": "Cluster not found"
}

{
  "detail": "Cluster not found"
}

{
  "detail": "Cluster not found"
}

{
  "detail": "Cluster not found"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

{
  "detail": "Cluster not found"
}

Authorizations

Authorization

string

header

required

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

Body

application/json

Create a self-managed Kubernetes cluster on Proxmox VE VMs.

name

string

required

Minimum string length: 1

credential_id

string<uuid>

required

ssh_key_credential_id

string<uuid>

required

The SSH key credential authorised on the cluster's VMs.

node

string

required

The Proxmox VE node the bastion (and, without placement_nodes, every VM) runs on. See the nodes catalog.

Minimum string length: 1

bridge

string

required

The bridge or SDN vnet the VMs attach to. See the bridges catalog.

Minimum string length: 1

description

string | null

placement_nodes

string[]

Two or more unique Proxmox VE nodes to spread the Kubernetes VMs across. Omit to keep every VM on node.

Minimum string length: 1

storage

string

default:local-lvm

The storage the VM disks are created on. See the storages catalog.

Minimum string length: 1

template

string

The template (VMID or name) to clone the VMs from. Omit to use Ankra's own template on the node.

bastion_instance_type

string

default:px-small

A size preset from the sizes catalog.

Minimum string length: 1

control_plane_count

integer

default:1

Required range: 1 <= x <= 5

control_plane_instance_type

string

default:px-medium

A size preset from the sizes catalog.

Minimum string length: 1

worker_count

integer

default:1

Required range: 0 <= x <= 50

worker_instance_type

string

default:px-medium

A size preset from the sizes catalog.

Minimum string length: 1

distribution

string

default:kubeadm

kubernetes_version

string | null

Version for the chosen distribution (kubeadm unless distribution says k3s). kubeadm takes a plain upstream tag such as v1.36.4; k3s takes a k3s build such as v1.35.7+k3s1, and a bare patch resolves to its newest +k3sN build. A +k3sN build with distribution kubeadm is refused. Omit to install the version catalogue's stable version for the distribution.

etcd_topology

string

default:stacked

etcd_node_count

integer

default:3

etcd_instance_type

string

default:px-medium

Size preset of the external etcd nodes; used with etcd_topology external.

cni

enum<string>

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

Available options:

flannel,

calico,

cilium

network_mode

enum<string>

private_network (the default when omitted) keeps the nodes on the SDN alone; wireguard_mesh puts them on the platform WireGuard overlay behind the bastion site gateway (kubeadm only, needs site_public_ip).

Available options:

private_network,

wireguard_mesh

site_public_ip

string

The address other sites dial this cluster's bastion on for the overlay. Required with network_mode wireguard_mesh.

node_groups

CreateNodeGroupRequest · object[] | null

Worker node groups, sized by size preset. Replaces worker_count and worker_instance_type when given.

Show child attributes

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

external_cloud_provider

boolean

default:false

Accepted only to be refused: the provider has no cloud controller manager, so true answers 400.

include_networking

boolean

default:true

include_dns

boolean

default:true

Opt the cluster into its delegated DNS subzone, which wires external-dns into the networking stack.

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.

environment

string | null

Required string length: 1 - 50

criticality

enum<string> | null

Available options:

production,

staging,

development,

disposable

Response

Cluster created; provisioning runs in the background

cluster_id

string<uuid>

required

name

string

required

API reference

Endpoints

Create a Proxmox VE cluster

Authorizations

Body

Response