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 follow the account's billing mode: pay-as-you-go accounts bill per node-hour; subscription accounts are billed monthly — the API validates the saved payment method, creates the subscription, and charges it automatically (same behavior as VM creation).

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_countinteger

Removed August 26, 2026 — every cluster includes the raff-block default StorageClass: PersistentVolumeClaims are provisioned as Volumes and billed per GB. Any value other than 0 is rejected.

storage_node_disk_gbinteger

Removed August 26, 2026 together with storage_node_count.

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
    }
  ]
}

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