Kubernetes service API reference

The Kubernetes API reference documents every Magnum endpoint with curl examples.

The Kubernetes service runs on the Container Infrastructure Management service (OpenStack Magnum). The HTTP API lives in the container-infra entry of the service catalog, not in the Compute (Nova) or Network (Neutron) catalogs.

In the paths below, {cluster_id}, {clustertemplate_id}, and {nodegroup_id} are placeholders. Replace each one with the UUID of the cluster, cluster template, or node group you are addressing. Request bodies use SCREAMING_SNAKE_CASE placeholders such as CLUSTER_NAME; replace each placeholder with a real value before sending the request.

Base URL and authentication#

All paths are relative to the container-infra service endpoint. Look the endpoint up in the service endpoints table for your region:

https://container-infra.{region}.rumble.cloud/v1

For example, the us-east-1 base URL is https://container-infra.us-east-1.rumble.cloud/v1.

Every request requires a Keystone token in the X-Auth-Token header. Requests with a body (POST and PATCH) also require Content-Type: application/json. To target a specific microversion, send the OpenStack-API-Version header; the service advertises a minimum of container-infra 1.1 and a maximum of container-infra 1.10.

X-Auth-Token: YOUR_TOKEN
Content-Type: application/json
OpenStack-API-Version: container-infra 1.10

Errors#

The service returns two error envelope shapes. Keystone rejects an unauthenticated request with its own envelope:

{
  "error": {
    "code": 401,
    "title": "Unauthorized",
    "message": "The request you have made requires authentication."
  }
}

Magnum reports validation and request errors with an errors array:

{
  "errors": [
    {
      "request_id": "",
      "code": "client",
      "status": 400,
      "title": "Invalid input for field/attribute cluster_template_id",
      "detail": "Invalid input for field/attribute cluster_template_id. Value: 'None'. Mandatory field missing.",
      "links": []
    }
  ]
}

Clusters#

List clusters#

GET /v1/clusters

Returns 200. The response wraps the results in a clusters array:

{
  "clusters": []
}

Show cluster details#

GET /v1/clusters/{cluster_id}

Returns 200 with the cluster object.

Create a cluster#

POST /v1/clusters

Returns 201. Counts are JSON integers, not strings. The keypair field on a cluster is named differently from the keypair_id field on a cluster template; this asymmetry mirrors Magnum's own schema.

Request body:

{
  "cluster_template_id": "CLUSTER_TEMPLATE_ID",
  "name": "CLUSTER_NAME",
  "master_count": 1,
  "node_count": 3,
  "keypair": "KEYPAIR_NAME",
  "labels": {
    "kube_tag": "v1.24.16-rancher1"
  }
}

Update a cluster#

PATCH /v1/clusters/{cluster_id}

Returns 202; the update runs asynchronously. The body is an RFC 6902 JSON-Patch document, which is an array of operations. Each value must match the target field's JSON type, so a node count is an integer.

Request body:

[
  {
    "op": "replace",
    "path": "/node_count",
    "value": 5
  }
]

Delete a cluster#

DELETE /v1/clusters/{cluster_id}

Returns 204.

Cluster templates#

List cluster templates#

GET /v1/clustertemplates

Returns 200. The response wraps the results in a clustertemplates array:

{
  "clustertemplates": [
    {
      "uuid": "2364d8e3-c4d7-469d-90f1-85664a39de83",
      "name": "Standard-v2.0-k8s-calico-fc38_v1.24.16",
      "coe": "kubernetes",
      "image_id": "FedoraCoreOS-38",
      "flavor_id": "m2a.2xlarge",
      "master_flavor_id": "m2a.xlarge",
      "dns_nameserver": "1.1.1.1,8.8.8.8",
      "keypair_id": null,
      "external_network_id": "PublicStatic",
      "network_driver": "calico",
      "docker_volume_size": 50,
      "volume_driver": "cinder",
      "cluster_distro": "fedora-coreos",
      "labels": {
        "kube_tag": "v1.24.16-rancher1"
      },
      "public": true,
      "server_type": "vm",
      "created_at": "2026-06-04T00:00:00+00:00",
      "updated_at": null
    }
  ]
}

Show cluster template details#

GET /v1/clustertemplates/{clustertemplate_id}

Returns 200 with the cluster template object.

Create a cluster template#

POST /v1/clustertemplates

Returns 201. docker_volume_size is a JSON integer in GB, not a string.

Request body:

{
  "name": "TEMPLATE_NAME",
  "image_id": "IMAGE_NAME_OR_ID",
  "keypair_id": "KEYPAIR_NAME",
  "external_network_id": "EXTERNAL_NETWORK_NAME_OR_ID",
  "dns_nameserver": "1.1.1.1,8.8.8.8",
  "flavor_id": "FLAVOR_NAME",
  "master_flavor_id": "FLAVOR_NAME",
  "docker_volume_size": 50,
  "network_driver": "calico",
  "volume_driver": "cinder",
  "coe": "kubernetes"
}

Update a cluster template#

PATCH /v1/clustertemplates/{clustertemplate_id}

Returns 200. The body is an RFC 6902 JSON-Patch array. Each value must match the target field's JSON type, so docker_volume_size is an integer.

Request body:

[
  {
    "op": "replace",
    "path": "/docker_volume_size",
    "value": 60
  }
]

The supported operations are add, replace, and remove.

Delete a cluster template#

DELETE /v1/clustertemplates/{clustertemplate_id}

Returns 204.

Node groups#

Node groups manage the worker pools of a cluster. The service nests them under a cluster, so every path carries a {cluster_id}.

List node groups#

GET /v1/clusters/{cluster_id}/nodegroups

Show node group details#

GET /v1/clusters/{cluster_id}/nodegroups/{nodegroup_id}

Create a node group#

POST /v1/clusters/{cluster_id}/nodegroups

Request body:

{
  "name": "NODEGROUP_NAME",
  "node_count": 2,
  "flavor_id": "FLAVOR_NAME",
  "role": "worker"
}

Update a node group#

PATCH /v1/clusters/{cluster_id}/nodegroups/{nodegroup_id}

The body is an RFC 6902 JSON-Patch array:

[
  {
    "op": "replace",
    "path": "/node_count",
    "value": 4
  }
]

Delete a node group#

DELETE /v1/clusters/{cluster_id}/nodegroups/{nodegroup_id}

Certificates#

The certificates endpoints back the cluster CA workflow (show, sign, and rotate).

Show the cluster CA certificate#

GET /v1/certificates/{cluster_id}

Sign a certificate#

POST /v1/certificates

Send a PEM certificate signing request for the cluster:

{
  "cluster_uuid": "CLUSTER_ID",
  "csr": "CERTIFICATE_SIGNING_REQUEST_PEM"
}

Rotate the cluster CA certificate#

PATCH /v1/certificates/{cluster_id}

Quotas#

Show project quotas#

GET /v1/quotas

Show one resource quota#

GET /v1/quotas/{project_id}/{resource}

Set a quota#

POST /v1/quotas

Request body:

{
  "project_id": "PROJECT_ID",
  "resource": "Cluster",
  "hard_limit": 10
}

Stats#

Show cluster statistics#

GET /v1/stats