Clusters

Create and manage workload Kubernetes clusters

List clusters

get

Returns all clusters in the namespace. The namespace is scoped to a single tenant ({du-name}-{keystone-domain}-{keystone-tenant}), so this effectively lists all clusters owned by that tenant.

Authorizations

BearerAuth

AuthorizationstringRequired

Dex-issued JWT token.

Path parameters

namespacestringRequired

Tenant namespace. Pattern: {du-name}-{keystone-domain}-{keystone-tenant}

Example: pcd-default-service

Responses

200

OK

application/json

apiVersionstringOptionalExample: cluster.x-k8s.io/v1beta1

kindstringOptionalExample: ClusterList

401

Missing or invalid JWT token.

application/json

403

Token does not have permission for this operation.

application/json

get/apis/cluster.x-k8s.io/v1beta1/namespaces/{namespace}/clusters

HTTPcURLJavaScriptPython

GET /oidc-proxy/service/r1/apis/cluster.x-k8s.io/v1beta1/namespaces/{namespace}/clusters HTTP/1.1
Host: pcd-r1.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "apiVersion": "cluster.x-k8s.io/v1beta1",
  "kind": "ClusterList",
  "metadata": {
    "resourceVersion": "text"
  },
  "items": [
    {
      "apiVersion": "cluster.x-k8s.io/v1beta1",
      "kind": "Cluster",
      "metadata": {
        "namespace": "pcd-default-service",
        "uid": "123e4567-e89b-12d3-a456-426614174000",
        "resourceVersion": "text",
        "creationTimestamp": "2026-08-12T01:02:17.860Z",
        "deletionTimestamp": "2026-08-12T01:02:17.860Z",
        "labels": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "finalizers": [
          "text"
        ]
      },
      "spec": {
        "controlPlaneEndpoint": {
          "host": "dev-cluster.default-service.k8s.pcd.example.com",
          "port": 443
        },
        "topology": {
          "version": "1.33.2",
          "class": "openstack-default-v1",
          "classNamespace": "kaapi",
          "workers": {
            "machineDeployments": [
              {
                "name": "md-0",
                "class": "ost-md",
                "replicas": 2,
                "failureDomain": "host-cluster1",
                "metadata": {
                  "annotations": {
                    "ANY_ADDITIONAL_PROPERTY": "text"
                  }
                },
                "variables": {
                  "overrides": [
                    {
                      "name": "workerNode",
                      "value": null
                    }
                  ]
                }
              }
            ]
          },
          "variables": [
            {
              "name": "text",
              "value": null
            }
          ]
        }
      },
      "status": {
        "phase": "Provisioning",
        "controlPlaneReady": true,
        "infrastructureReady": true,
        "failureMessage": "text",
        "failureDomains": {
          "ANY_ADDITIONAL_PROPERTY": {
            "controlPlane": true
          }
        },
        "conditions": [
          {
            "type": "Ready",
            "status": "True",
            "reason": "text",
            "message": "text",
            "lastTransitionTime": "2026-08-12T01:02:17.860Z"
          }
        ]
      }
    }
  ]
}

Create a cluster

post

Creates a new workload Kubernetes cluster using ClusterClass topology mode.

The cluster webhook automatically sets labels, clusterNetwork CIDRs, controlPlaneEndpoint, topology.class/classNamespace, do not include these in the request. Also it merges default for apiServerFlags, kubeadmConfigFiles, and customSecurityGroupRules with user provided values.

Class selection (resolved from variables, no need to set explicitly):

infrastructure.type	deploymentUnit.type	ClusterClass used
openstack (default)	saas (default)	openstack-default-v1
openstack	onprem	openstack-default-v1
byoh	any	byoh-default-v1

Node pool variables: workerNode can be set at two levels. Set it in spec.topology.variables as a cluster-wide default (applies to all pools), and/or in a pool's variables.overrides to override for that pool specifically. Pool-level overrides take precedence. In GET responses you will see the cluster-level workerNode variable alongside pool-level overrides — both are normal.

Authorizations

BearerAuth

AuthorizationstringRequired

Dex-issued JWT token.

Path parameters

namespacestringRequired

Tenant namespace. Pattern: {du-name}-{keystone-domain}-{keystone-tenant}

Example: pcd-default-service

Body

application/json

apiVersionstring · enumRequiredPossible values:

kindstring · enumRequiredPossible values:

Responses

201

Created — provisioning is asynchronous.

application/json

apiVersionstring · enumRequiredPossible values:

kindstring · enumRequiredPossible values:

400

Malformed request body.

application/json

401

Missing or invalid JWT token.

application/json

403

Token does not have permission for this operation.

application/json

409

A cluster with this name already exists.

application/json

422

Admission webhook rejected the request due to a validation failure.

application/json

post/apis/cluster.x-k8s.io/v1beta1/namespaces/{namespace}/clusters

HTTPcURLJavaScriptPython

POST /oidc-proxy/service/r1/apis/cluster.x-k8s.io/v1beta1/namespaces/{namespace}/clusters HTTP/1.1
Host: pcd-r1.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 664

{
  "apiVersion": "cluster.x-k8s.io/v1beta1",
  "kind": "Cluster",
  "metadata": {
    "name": "dev-cluster"
  },
  "spec": {
    "topology": {
      "version": "1.33.2",
      "workers": {
        "machineDeployments": [
          {
            "name": "md-0",
            "class": "ost-md",
            "replicas": 2,
            "failureDomain": "host-cluster1",
            "variables": {
              "overrides": [
                {
                  "name": "workerNode",
                  "value": {
                    "flavor": "m1.medium",
                    "imageName": "ub22-k8s-133"
                  }
                }
              ]
            }
          }
        ]
      },
      "variables": [
        {
          "name": "deploymentUnit",
          "value": {
            "name": "pcd",
            "domain": "example.com",
            "region": "r1"
          }
        },
        {
          "name": "network",
          "value": {
            "networkID": "e0d4bd81-b9ca-4454-87ae-f52af394132e",
            "subnetID": "86aa8162-d835-4f25-9906-4f4a9f1e4fbf"
          }
        },
        {
          "name": "workerNode",
          "value": {
            "flavor": "m1.medium",
            "imageName": "ub22-k8s-133"
          }
        }
      ]
    }
  }
}

OpenStack cluster (SaaS)BYOH cluster (pre-provisioned hosts)Multi-pool OpenStack clusterOn-prem OpenStack cluster

{
  "apiVersion": "cluster.x-k8s.io/v1beta1",
  "kind": "Cluster",
  "metadata": {
    "namespace": "pcd-default-service",
    "uid": "123e4567-e89b-12d3-a456-426614174000",
    "resourceVersion": "text",
    "creationTimestamp": "2026-08-12T01:02:17.860Z",
    "deletionTimestamp": "2026-08-12T01:02:17.860Z",
    "labels": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "finalizers": [
      "text"
    ]
  },
  "spec": {
    "controlPlaneEndpoint": {
      "host": "dev-cluster.default-service.k8s.pcd.example.com",
      "port": 443
    },
    "topology": {
      "version": "1.33.2",
      "class": "openstack-default-v1",
      "classNamespace": "kaapi",
      "workers": {
        "machineDeployments": [
          {
            "name": "md-0",
            "class": "ost-md",
            "replicas": 2,
            "failureDomain": "host-cluster1",
            "metadata": {
              "annotations": {
                "ANY_ADDITIONAL_PROPERTY": "text"
              }
            },
            "variables": {
              "overrides": [
                {
                  "name": "workerNode",
                  "value": null
                }
              ]
            }
          }
        ]
      },
      "variables": [
        {
          "name": "text",
          "value": null
        }
      ]
    }
  },
  "status": {
    "phase": "Provisioning",
    "controlPlaneReady": true,
    "infrastructureReady": true,
    "failureMessage": "text",
    "failureDomains": {
      "ANY_ADDITIONAL_PROPERTY": {
        "controlPlane": true
      }
    },
    "conditions": [
      {
        "type": "Ready",
        "status": "True",
        "reason": "text",
        "message": "text",
        "lastTransitionTime": "2026-08-12T01:02:17.860Z"
      }
    ]
  }
}

Get a cluster

get

Returns the full Cluster object including status.

status.phase	Description
Provisioning	Control plane and/or workers are being created
Provisioned	Cluster is ready — control plane and all worker pools are up
Deleting	Delete is in progress
Failed	Provisioning failed — check status.failureMessage

Authorizations

BearerAuth

AuthorizationstringRequired

Dex-issued JWT token.

Path parameters

namespacestringRequired

Tenant namespace. Pattern: {du-name}-{keystone-domain}-{keystone-tenant}

Example: pcd-default-service

namestringRequiredExample: dev-cluster

Responses

200

OK

application/json

apiVersionstring · enumRequiredPossible values:

kindstring · enumRequiredPossible values:

401

Missing or invalid JWT token.

application/json

403

Token does not have permission for this operation.

application/json

404

Resource not found.

application/json

get/apis/cluster.x-k8s.io/v1beta1/namespaces/{namespace}/clusters/{name}

HTTPcURLJavaScriptPython

GET /oidc-proxy/service/r1/apis/cluster.x-k8s.io/v1beta1/namespaces/{namespace}/clusters/{name} HTTP/1.1
Host: pcd-r1.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "apiVersion": "cluster.x-k8s.io/v1beta1",
  "kind": "Cluster",
  "metadata": {
    "name": "dev-cluster",
    "namespace": "pcd-default-service",
    "uid": "00000000-0000-0000-0000-000000000001",
    "resourceVersion": "100000",
    "creationTimestamp": "2024-01-01T10:00:00Z",
    "finalizers": [
      "cluster.cluster.x-k8s.io"
    ],
    "labels": {
      "cas-capi-version": "v1.33",
      "core-addons": "enabled",
      "kaapi.pf9.io/infra-addon": "openstack",
      "pcd-kaapi.pf9.io/region": "r1",
      "proxy-addons": "enabled"
    }
  },
  "spec": {
    "controlPlaneEndpoint": {
      "host": "dev-cluster.default-service.k8s.pcd.example.com",
      "port": 443
    },
    "topology": {
      "class": "openstack-default-v1",
      "classNamespace": "kaapi",
      "version": "v1.33.2",
      "variables": [
        {
          "name": "deploymentUnit",
          "value": {
            "name": "pcd",
            "domain": "example.com",
            "region": "r1",
            "keystoneDomain": "default",
            "keystoneTenant": "service",
            "type": "saas",
            "vip": ""
          }
        },
        {
          "name": "network",
          "value": {
            "networkID": "e0d4bd81-b9ca-4454-87ae-f52af394132e",
            "subnetID": "86aa8162-d835-4f25-9906-4f4a9f1e4fbf"
          }
        },
        {
          "name": "workerNode",
          "value": {
            "flavor": "m1.medium",
            "imageName": "ub22-k8s-133"
          }
        },
        {
          "name": "apiServerFlags",
          "value": [
            "--advertise-address=10.96.0.40",
            "--authentication-config=/etc/kubernetes/oidc-auth/oidc.yaml"
          ]
        }
      ],
      "workers": {
        "machineDeployments": [
          {
            "name": "md-0",
            "class": "ost-md",
            "replicas": 2,
            "failureDomain": "host-cluster1",
            "variables": {
              "overrides": [
                {
                  "name": "workerNode",
                  "value": {
                    "flavor": "m1.medium",
                    "imageName": "ub22-k8s-133"
                  }
                },
                {
                  "name": "network",
                  "value": {
                    "networkID": "e0d4bd81-b9ca-4454-87ae-f52af394132e",
                    "subnetID": "86aa8162-d835-4f25-9906-4f4a9f1e4fbf"
                  }
                }
              ]
            }
          }
        ]
      }
    }
  },
  "status": {
    "phase": "Provisioned",
    "controlPlaneReady": true,
    "infrastructureReady": true,
    "failureDomains": {
      "host-cluster1": {
        "controlPlane": true
      }
    },
    "conditions": [
      {
        "type": "Ready",
        "status": "True",
        "lastTransitionTime": "2024-01-01T10:05:00Z"
      },
      {
        "type": "ControlPlaneInitialized",
        "status": "True",
        "lastTransitionTime": "2024-01-01T10:04:30Z"
      },
      {
        "type": "ControlPlaneReady",
        "status": "True",
        "lastTransitionTime": "2024-01-01T10:04:00Z"
      },
      {
        "type": "InfrastructureReady",
        "status": "True",
        "lastTransitionTime": "2024-01-01T10:03:00Z"
      },
      {
        "type": "TopologyReconciled",
        "status": "True",
        "lastTransitionTime": "2024-01-01T10:01:00Z"
      }
    ]
  }
}

Delete a cluster

delete

Deletes the cluster and all owned resources (control plane, workers, OpenStack infrastructure). Asynchronous — cluster transitions to status.phase == "Deleting" and is removed when complete. Typical deletion time is 2–5 minutes.

BYOH clusters: physical host nodes are not deprovisioned. The cluster label is removed from the hosts, which return to the unallocated pool and can be reused by another cluster.

Authorizations

BearerAuth

AuthorizationstringRequired

Dex-issued JWT token.

Path parameters

namespacestringRequired

Tenant namespace. Pattern: {du-name}-{keystone-domain}-{keystone-tenant}

Example: pcd-default-service

namestringRequiredExample: dev-cluster

Responses

200

Deletion accepted. Returns the Cluster object with metadata.deletionTimestamp set. The cluster is fully removed once status.phase disappears (resource deleted).

application/json

apiVersionstring · enumRequiredPossible values:

kindstring · enumRequiredPossible values:

401

Missing or invalid JWT token.

application/json

403

Token does not have permission for this operation.

application/json

404

Resource not found.

application/json

delete/apis/cluster.x-k8s.io/v1beta1/namespaces/{namespace}/clusters/{name}

HTTPcURLJavaScriptPython

DELETE /oidc-proxy/service/r1/apis/cluster.x-k8s.io/v1beta1/namespaces/{namespace}/clusters/{name} HTTP/1.1
Host: pcd-r1.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "apiVersion": "cluster.x-k8s.io/v1beta1",
  "kind": "Cluster",
  "metadata": {
    "namespace": "pcd-default-service",
    "uid": "123e4567-e89b-12d3-a456-426614174000",
    "resourceVersion": "text",
    "creationTimestamp": "2026-08-12T01:02:17.860Z",
    "deletionTimestamp": "2026-08-12T01:02:17.860Z",
    "labels": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "finalizers": [
      "text"
    ]
  },
  "spec": {
    "controlPlaneEndpoint": {
      "host": "dev-cluster.default-service.k8s.pcd.example.com",
      "port": 443
    },
    "topology": {
      "version": "1.33.2",
      "class": "openstack-default-v1",
      "classNamespace": "kaapi",
      "workers": {
        "machineDeployments": [
          {
            "name": "md-0",
            "class": "ost-md",
            "replicas": 2,
            "failureDomain": "host-cluster1",
            "metadata": {
              "annotations": {
                "ANY_ADDITIONAL_PROPERTY": "text"
              }
            },
            "variables": {
              "overrides": [
                {
                  "name": "workerNode",
                  "value": null
                }
              ]
            }
          }
        ]
      },
      "variables": [
        {
          "name": "text",
          "value": null
        }
      ]
    }
  },
  "status": {
    "phase": "Provisioning",
    "controlPlaneReady": true,
    "infrastructureReady": true,
    "failureMessage": "text",
    "failureDomains": {
      "ANY_ADDITIONAL_PROPERTY": {
        "controlPlane": true
      }
    },
    "conditions": [
      {
        "type": "Ready",
        "status": "True",
        "reason": "text",
        "message": "text",
        "lastTransitionTime": "2026-08-12T01:02:17.860Z"
      }
    ]
  }
}

Update a cluster

patch

Two content types are supported depending on the operation:

application/json-patch+json — for node pool (MachineDeployment) operations. spec.topology.workers.machineDeployments is an array with no server-side name-keying for this patch type, so elements must be addressed by their zero-based index. Do a GET first to find the position of the pool you want to modify.

application/apply-patch+yaml (Server-Side Apply) — for named topology variables such as apiServerFlags .

Autoscaling: to enable, remove the replicas field (so the autoscaler controls it) and add both min/max annotations in the same request. To disable, restore a fixed replicas value and remove both annotations.

Do not patch spec.topology.version directly.

Authorizations

BearerAuth

AuthorizationstringRequired

Dex-issued JWT token.

Path parameters

namespacestringRequired

Tenant namespace. Pattern: {du-name}-{keystone-domain}-{keystone-tenant}

Example: pcd-default-service

namestringRequiredExample: dev-cluster

Query parameters

fieldManagerstringOptional

Name of the field manager. Required when using application/apply-patch+yaml (Server-Side Apply) — any non-empty string is valid (e.g. kubectl, my-app). Not needed for application/json-patch+json.

Example: kubectl

Bodyobject[]

application/json-patch+jsonapplication/apply-patch+yaml

opstring · enumRequiredPossible values:

pathstringRequired

valueanyOptional

Responses

200

Patch applied — changes take effect asynchronously.

application/json

apiVersionstring · enumRequiredPossible values:

kindstring · enumRequiredPossible values:

400

Malformed request body.

application/json

401

Missing or invalid JWT token.

application/json

403

Token does not have permission for this operation.

application/json

404

Resource not found.

application/json

422

Admission webhook rejected the request due to a validation failure.

application/json

patch/apis/cluster.x-k8s.io/v1beta1/namespaces/{namespace}/clusters/{name}

HTTPcURLJavaScriptPython

PATCH /oidc-proxy/service/r1/apis/cluster.x-k8s.io/v1beta1/namespaces/{namespace}/clusters/{name} HTTP/1.1
Host: pcd-r1.example.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 90

[
  {
    "op": "replace",
    "path": "/spec/topology/workers/machineDeployments/0/replicas",
    "value": 4
  }
]

application/json-patch+jsonapplication/apply-patch+yaml

Scale node pool at index 0 to 4 replicasAdd a new node poolRemove node pool at index 1 (do a GET first to confirm the index)Enable autoscaler on pool at index 0 (remove fixed replicas, set min/max)Update min/max bounds on a pool that already has autoscaling enabledDisable autoscaler on pool at index 0 (restore fixed replicas, remove annotations)Set rolling update strategy on pool at index 0

{
  "apiVersion": "cluster.x-k8s.io/v1beta1",
  "kind": "Cluster",
  "metadata": {
    "namespace": "pcd-default-service",
    "uid": "123e4567-e89b-12d3-a456-426614174000",
    "resourceVersion": "text",
    "creationTimestamp": "2026-08-12T01:02:17.860Z",
    "deletionTimestamp": "2026-08-12T01:02:17.860Z",
    "labels": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "finalizers": [
      "text"
    ]
  },
  "spec": {
    "controlPlaneEndpoint": {
      "host": "dev-cluster.default-service.k8s.pcd.example.com",
      "port": 443
    },
    "topology": {
      "version": "1.33.2",
      "class": "openstack-default-v1",
      "classNamespace": "kaapi",
      "workers": {
        "machineDeployments": [
          {
            "name": "md-0",
            "class": "ost-md",
            "replicas": 2,
            "failureDomain": "host-cluster1",
            "metadata": {
              "annotations": {
                "ANY_ADDITIONAL_PROPERTY": "text"
              }
            },
            "variables": {
              "overrides": [
                {
                  "name": "workerNode",
                  "value": null
                }
              ]
            }
          }
        ]
      },
      "variables": [
        {
          "name": "text",
          "value": null
        }
      ]
    }
  },
  "status": {
    "phase": "Provisioning",
    "controlPlaneReady": true,
    "infrastructureReady": true,
    "failureMessage": "text",
    "failureDomains": {
      "ANY_ADDITIONAL_PROPERTY": {
        "controlPlane": true
      }
    },
    "conditions": [
      {
        "type": "Ready",
        "status": "True",
        "reason": "text",
        "message": "text",
        "lastTransitionTime": "2026-08-12T01:02:17.860Z"
      }
    ]
  }
}