Skip to main content
PATCH/vault/hyok/clusters/{cluster_id}

Update Cluster

Renames a cluster, moves it to another region or replaces its hosts.

The customer key is unchanged, so no data key is re-wrapped.

A cluster left with no hosts becomes inactive, and one with hosts active.

A region change is refused while a project is attached.

Needs ORG_ADMIN.

Parameters
orgId *query

The organisation's id.

cluster_id *path

The cluster's id: hyokcluster_ and a UUID.

Request body
hostIdsstring[] | null

Replace the member-host set (add/remove). None (omitted) leaves membership unchanged; Some([]) empties the cluster.

Every id must be a host registered in this org.

namestring | null

New cluster name.

Example: "luna-prod-eu-2"
regionstring | null

New region.

Example: "de01"
Responses
HTTPK9O CodeDescription
200The updated cluster.
400A field isn't valid, or a host doesn't exist.
404No such cluster.
409`K9O_HYOK_CLUSTER_IN_USE`: a region change while a project is attached.
500An internal error. Retry later.
Response body (200)
attachedProjectIds *string[]

Project IDs currently in HYOK mode using this cluster.

createdAt *string <date-time>

Cluster creation timestamp.

Example: "2026-11-01T08:00:00.000Z"
hostIds *string[]

IDs of hosts in this cluster.

id *string

Cluster identifier — UUID prefixed "hyokcluster_".

Example: "hyokcluster_0b6f2c1e-3d4a-4b5c-8d9e-0f1a2b3c4d5e"
name *string

Human-readable cluster name.

Example: "luna-prod-eu"
orgId *string

Owning org.

Example: "org_8kP3wQ9zLm2X"
region *string

Region — must match the Kibo project's region pin at attach time.

Example: "de01"
status *"active" | "warning" | "degraded" | "inactive"

HYOK cluster operational status.

cURL
curl -X PATCH 'https://<org>.api-<region>.k9o.io/@storefront/vault/hyok/clusters/<clusterId>' \
  -H 'Authorization: Bearer $K9O_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "luna-prod-eu-2",
  "hostIds": [
    "hyokhost_9e8d7c6b-5a49-4f3e-8d2c-1b0a9f8e7d6c",
    "hyokhost_1a2b3c4d-5e6f-4a7b-9c8d-0e1f2a3b4c5d"
  ]
}'

Showing example in cURL

Request example
{
  "name": "luna-prod-eu-2",
  "hostIds": [
    "hyokhost_9e8d7c6b-5a49-4f3e-8d2c-1b0a9f8e7d6c",
    "hyokhost_1a2b3c4d-5e6f-4a7b-9c8d-0e1f2a3b4c5d"
  ]
}
Response example (200)
{
  "attachedProjectIds": [
    "3f2b8c1e-5d4a-4e6f-9a7b-1c2d3e4f5a6b"
  ],
  "createdAt": "2026-11-01T08:00:00.000Z",
  "hostIds": [
    "hyokhost_9e8d7c6b-5a49-4f3e-8d2c-1b0a9f8e7d6c"
  ],
  "id": "hyokcluster_0b6f2c1e-3d4a-4b5c-8d9e-0f1a2b3c4d5e",
  "name": "luna-prod-eu",
  "orgId": "org_8kP3wQ9zLm2X",
  "region": "de01",
  "status": "active"
}

More in HYOK Clusters & Hosts