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.

mutation {
  updateCluster(
    id: "<cluster-id>"
    status: INACTIVE
    statusReason: { message: "Maintenance window — cluster offline for upgrades" }
  ) {
    id
    status
    statusReason
  }
}

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:

mutation {
  updateCluster(
    id: "<cluster-id>"
    status: ACTIVE
    statusReason: { message: "Manually verified healthy" }
  ) {
    id
    status
  }
}

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

Change the cluster configuration

deploymentsConfigOverride is merged into the stored cluster override. Keys that you leave out keep their stored values. Starting in APC 2.2, updateCluster also applies the following rules:

APC rejects null, and the error names the key. To remove a key, set it to "DELETE_KEY". See Remove a setting.
APC rejects a new value at a path that the data plane supplies. Cluster.readOnlyConfigPaths lists these paths. See Values the data plane supplies.

mutation {
  updateCluster(
    id: "<cluster-id>"
    deploymentsConfigOverride: {
      helm: {
        airflow: {
          labels: {
            team: "DELETE_KEY"
          }
        }
      }
    }
  ) {
    id
    configOverrideRemovedPaths
  }
}

configOverrideRemovedPaths lists the paths that the cluster override removes, each as an array of key segments. A removal that only withdraws isn’t listed.

Restore a removed setting

Starting in APC 2.2, pass clearConfigOverridePaths to undo a removal that the cluster override stores. Each path is an array of key segments below deployments, and a key that contains dots is one segment. Restoring puts back the platform default, or leaves the key unset where there is no platform default.

mutation {
  updateCluster(
    id: "<cluster-id>"
    clearConfigOverridePaths: [["helm", "airflow", "labels", "team"]]
  ) {
    id
    configOverrideRemovedPaths
  }
}

Every path must hold a stored "DELETE_KEY", as listed by configOverrideRemovedPaths, or APC rejects the call. You can’t combine clearConfigOverridePaths with a deploymentsConfigOverride that changes the same path. To control whether the cluster derives its configuration from the current platform defaults, use the updateClusterConfigDerive mutation. See Derive cluster configuration from platform defaults.

⌘I