APC APIExample mutationsClusters

Update a cluster with the APC API

The examples on this page show common ways to use the APC API — they’re not a complete API reference. For the full, interactive API documentation for your installation, including every available query, mutation, and type, go to https://houston.<your-base-domain>/v1, and click on the Docs tab. See Develop and test APC API queries for more on using the built-in GraphQL explorer.

A user with permission to update clusters can change a cluster’s status manually. The statusReason argument accepts a JSON object whose shape isn’t enforced by the schema, but the APC API itself writes the value the deployment orchestrator returns in its /metadata response when reconciling. To stay consistent, use the same shape the APC API uses or include a descriptive message field.

1mutation {
2  updateCluster(
3    id: "<cluster-id>"
4    status: INACTIVE
5    statusReason: { message: "Maintenance window — cluster offline for upgrades" }
6  ) {
7    id
8    status
9    statusReason
10  }
11}

For status changes, supply id (required), status, and statusReason. The updateCluster mutation also accepts name and deploymentsConfigOverride for non-status changes; see Update data plane cluster configurations for those workflows.

The APC API blocks configuration updates (deploymentsConfigOverride, name) while the cluster status is INACTIVE and returns the error This operation is not allowed as the cluster is not active. Status itself can still be updated in any state.

To manually restore a cluster to ACTIVE after confirming it’s healthy:

1mutation {
2  updateCluster(
3    id: "<cluster-id>"
4    status: ACTIVE
5    statusReason: { message: "Manually verified healthy" }
6  ) {
7    id
8    status
9  }
10}

For querying cluster status and troubleshooting unhealthy clusters, see Manage cluster status. For updating a cluster’s deploymentsConfigOverride, see Update data plane cluster configurations.