Sign in
Kubernetes

Create Kubernetes cluster

Create a managed Kubernetes cluster. Provisioning is asynchronous — the response returns immediately with pending status; the cluster is usable when ready is true (typically 8–12 minutes).

API-created clusters are billed pay-as-you-go per node-hour. Accounts on subscription billing cannot create clusters through the API yet and receive 402 — use the dashboard instead.

Retries are safe with an Idempotency-Key header: a repeated request with the same key returns the cluster created by the first request instead of provisioning a second one.

post/api/v1/k8s/clusters

Headers

X-Project-IDstring uuid required

Project ID. Required for all mutating operations (create, delete, power actions, resize).

Idempotency-Keystring

Any unique string (max 128 chars). Reuse the same value when retrying a failed or timed-out request.

Request body

namestring required

1–63 lowercase letters, digits or hyphens; unique within the account

k8s_version_idinteger

From List Kubernetes versions. Omit for the default version.

ha_enabledboolean

3-master highly available control plane (flat monthly fee)

firewall_enabledboolean

Attach the platform baseline firewall to the public gateway

firewall_security_group_idstring uuid

Use one of your security groups instead of the baseline

storage_node_count0 | 2 | 3

Dedicated Longhorn storage nodes (0 disables in-cluster block storage)

storage_node_disk_gbinteger

Data disk per storage node; required when storage_node_count > 0. Bounds from List Kubernetes node plans storage_pricing.

traefik_enabledboolean

Install the Traefik ingress controller

metallb_enabledboolean

Install MetalLB for LoadBalancer services

cluster_cidrstring

Pod network override (private IPv4, /12–/24)

service_cidrstring

Service network override (private IPv4, /12–/24)

region'us-east'

Example request

{
  "name": "prod",
  "k8s_version_id": 1,
  "node_pools": [
    {
      "name": "default-pool",
      "node_count": 3,
      "plan_id": 11
    }
  ],
  "storage_node_disk_gb": 100
}

Response

Cluster accepted for provisioning (status pending)

successboolean

Example response

{
  "cluster": {
    "cluster_id": "q7z7zg",
    "name": "prod",
    "dns_domain": "q7z7zg.k8s.raffusercloud.com",
    "api_endpoint": "https://q7z7zg.k8s.raffusercloud.com:6443",
    "k8s_version": "v1.33.4+rke2r1",
    "private_vip": "10.1.0.254"
  }
}

Changes