# Update Cluster

`PATCH /vault/hyok/clusters/{cluster_id}` · Keys & Secrets · HYOK Clusters & Hosts

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

| Name | In | Required | Description |
|---|---|---|---|
| `orgId` | query | yes | The organisation's id. Example: `"org_O3QAqchb6v7d"`. |
| `cluster_id` | path | yes | The cluster's id: `hyokcluster_` and a UUID. Example: `"hyokcluster_2d7e9f1a-4b6c-4d8e-9f0a-1b2c3d4e5f6a"`. |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `hostIds` | array of string \| null | no | 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. Example: `["hyokhost_9e8d7c6b-5a49-4f3e-8d2c-1b0a9f8e7d6c","hyokhost_1a2b3c4d-5e6f-4a7b-9c8d-0e1f2a3b4c5d"]`. |
| `name` | string \| null | no | New cluster name. Example: `"luna-prod-eu-2"`. |
| `region` | string \| null | no | New region. Example: `"de01"`. |

```json
{
  "name": "luna-prod-eu-2",
  "hostIds": [
    "hyokhost_9e8d7c6b-5a49-4f3e-8d2c-1b0a9f8e7d6c",
    "hyokhost_1a2b3c4d-5e6f-4a7b-9c8d-0e1f2a3b4c5d"
  ]
}
```

## Responses

- **200**: The updated cluster.

| Field | Type | Required | Description |
|---|---|---|---|
| `attachedProjectIds` | array of string | yes | Project IDs currently in HYOK mode using this cluster. Example: `["3f2b8c1e-5d4a-4e6f-9a7b-1c2d3e4f5a6b"]`. |
| `createdAt` | string (date-time) | yes | Cluster creation timestamp. Example: `"2026-11-01T08:00:00.000Z"`. |
| `hostIds` | array of string | yes | IDs of hosts in this cluster. Example: `["hyokhost_9e8d7c6b-5a49-4f3e-8d2c-1b0a9f8e7d6c"]`. |
| `id` | string | yes | Cluster identifier — UUID prefixed `"hyokcluster_"`. Example: `"hyokcluster_0b6f2c1e-3d4a-4b5c-8d9e-0f1a2b3c4d5e"`. |
| `name` | string | yes | Human-readable cluster name. Example: `"luna-prod-eu"`. |
| `orgId` | string | yes | Owning org. Example: `"org_8kP3wQ9zLm2X"`. |
| `region` | string | yes | Region — must match the Kibo project's region pin at attach time. Example: `"de01"`. |
| `status` | enum ("active", "warning", "degraded", "inactive") | yes | HYOK cluster operational status. |


## Errors

| HTTP | Description |
|---|---|
| 400 | A field isn't valid, or a host doesn't exist. |
| 404 | No such cluster. |
| 409 | `K9O_HYOK_CLUSTER_IN_USE`: a region change while a project is attached. |
| 500 | An internal error. Retry later. |

## Code samples

### cURL

```bash
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"
  ]
}'
```

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/vault/hyok/clusters/<clusterId>', {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.K9O_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "name": "luna-prod-eu-2",
  "hostIds": [
    "hyokhost_9e8d7c6b-5a49-4f3e-8d2c-1b0a9f8e7d6c",
    "hyokhost_1a2b3c4d-5e6f-4a7b-9c8d-0e1f2a3b4c5d"
  ]
}),
});
const { data, meta } = await res.json();
```


Canonical page: https://docs.kilimanjaro.dev/api-playground/keys-secrets/update-cluster
