Manage node pools 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, including every query, mutation, and type, go to https://houston.<your-base-domain>/v1, and click the Docs tab. See Develop and test APC API queries for more on using the built-in GraphQL explorer.

A node pool describes a node group that already exists in a data plane cluster, so you can place worker queues on it. For what node pools do and how to manage them from the UI, see Configure node pools.

Astro Private Cloud 2.2This feature was introduced in Astro Private Cloud 2.2. To access this feature, upgrade your Astro Private Cloud installation to 2.2 or later.

These operations need the system.nodePools.* or cluster.nodePools.* permissions. See Permissions.

List node pools on a cluster

query nodePools($clusterId: Uuid!) {
  nodePools(clusterId: $clusterId) {
    id
    name
    description
    nodeSelector
    tolerations {
      key
      operator
      value
      effect
      tolerationSeconds
    }
    maxCpu
    maxMemory
    maxEphemeralStorage
    maxNodeCount
    workerQueueCount
    capacity {
      cpu { budget committed }
      memory { budget committed }
      ephemeralStorage { budget committed }
      overCommitted
    }
  }
}

workerQueueCount is how many worker queues reference the pool. capacity.overCommitted is true when those queues, counted at their maximum worker counts, request more than the pool’s total. Over-commitment is a warning, not a block. capacity accepts an excludeDeploymentId argument, so a client editing one Deployment can show the pool’s committed total without double-counting that Deployment’s queues. To see which queues are on a pool, request workerQueueClaims. The field returns null for a caller without node pool read permission:

query nodePools($clusterId: Uuid!) {
  nodePools(clusterId: $clusterId) {
    name
    workerQueueClaims {
      deploymentId
      releaseName
      workerQueueName
      cpu
      memory
      ephemeralStorage
      maxWorkers
    }
  }
}

Create a node pool

mutation createNodePool($clusterId: Uuid!, $input: InputNodePool!) {
  createNodePool(clusterId: $clusterId, input: $input) {
    id
    name
    nodeSelector
    maxCpu
    maxMemory
  }
}

With these variables:

{
  "clusterId": "<cluster-id>",
  "input": {
    "name": "compute-optimized",
    "description": "Nodes reserved for ETL workloads",
    "nodeSelector": {
      "node-role": "etl"
    },
    "tolerations": [
      {
        "key": "workload",
        "operator": "Equal",
        "value": "airflow",
        "effect": "NoSchedule"
      }
    ],
    "maxCpu": 15000,
    "maxMemory": 30720,
    "maxEphemeralStorage": 51200,
    "maxNodeCount": 12
  }
}

InputNodePool fields

Field	Type	Required	Description
`name`	`String!`	Yes	Unique within the cluster. The same name on another cluster is allowed
`description`	`String`	No	Free-text note. Not used for scheduling
`nodeSelector`	`JSON!`	Yes	A flat object of string label keys to string values. `{}` means any node
`tolerations`	`[InputToleration!]`	No	One entry per taint on these nodes
`maxCpu`	`Int`	No	CPU one node gives a worker, in millicores
`maxMemory`	`Int`	No	Memory one node gives a worker, in MiB
`maxEphemeralStorage`	`Int`	No	Ephemeral storage one node gives a worker, in MiB
`maxNodeCount`	`Int`	No	How many of these nodes worker queues can use

Each max* value must be a whole number greater than zero. Leaving one unset means the pool imposes no ceiling on that dimension, and only the platform resource limits apply.

`InputToleration` fields

Field	Type	Description
`key`	`String`	The taint key. Leave it unset only with the `Exists` operator
`operator`	`TolerationOperator`	`Exists` or `Equal`
`value`	`String`	Must be empty when the operator is `Exists`
`effect`	`TolerationEffect`	`NoSchedule`, `PreferNoSchedule`, or `NoExecute`. Leave it unset to match every effect
`tolerationSeconds`	`Int`	Applies only to the `NoExecute` effect

Update a node pool

mutation updateNodePool($nodePoolId: Uuid!, $input: InputNodePool!) {
  updateNodePool(nodePoolId: $nodePoolId, input: $input) {
    id
    name
    maxCpu
    pendingConvergenceDeploymentIds
  }
}

name and nodeSelector are non-null on InputNodePool, so every update must resend both. A call that sends only { "maxCpu": null } fails schema validation. The optional fields behave as a partial patch, unlike InputWorkerQueue on upsertDeployment:

An optional field you omit keeps its stored value.
An optional field you set to null is cleared.

Clear a ceiling with an explicit null. This is the only way to fix a mis-set ceiling, because a pool that’s in use can’t be deleted and recreated. Renaming a pool is safe. Worker queues reference a pool by its identifier, so a rename can’t orphan them. A name that collides with another pool on the same cluster is refused.

Converge Deployments after a placement change

Changing nodeSelector or tolerations doesn’t reach Deployments that already use the pool until you rebuild each one. pendingConvergenceDeploymentIds reports which Deployments aren’t running the pool’s current placement, without reading resources back from the cluster. Rebuild exactly those Deployments:

mutation upgradeDeploymentsForNodePoolConvergence($nodePoolId: Uuid!) {
  upgradeDeploymentsForNodePoolConvergence(nodePoolId: $nodePoolId) {
    success
    upgradedDeploymentIds
    skipped {
      deploymentId
      reason
    }
  }
}

This mutation never touches the rest of the cluster.

Delete a node pool

mutation deleteNodePool($nodePoolId: Uuid!) {
  deleteNodePool(nodePoolId: $nodePoolId) {
    id
    name
  }
}

A pool that any worker queue references can’t be deleted. The error names the Deployments and queues that still use it. Move or remove those queues first. Node pools are hard-deleted, with no soft delete and no recovery.

Errors

Error	Cause
`ResourceNotFoundError`	The `nodePoolId` or `clusterId` doesn’t exist
`NodePoolInUseError`	You tried to delete a pool that worker queues still reference. The message lists the Deployment and queue for each
`NodePoolCeilingBelowWorkerQueuesError`	You lowered a ceiling below what an existing queue requests. The message names every offending Deployment, queue, field, requested value, and new ceiling
`Node pool "<name>" already exists on this cluster`	A name collision within the cluster
`Node pool nodeSelector must be an object of label keys to string values`	`nodeSelector` isn’t a flat string-to-string object
`Toleration N: operator must be Exists when no key is given, because an empty key matches every taint`	A toleration has no key and an operator other than `Exists`
`Toleration N: value must be empty when the operator is Exists`	A value was supplied with the `Exists` operator
`Toleration N: tolerationSeconds only applies to the NoExecute effect`	`tolerationSeconds` was set on another effect
`Node pool <field> must be greater than 0`	A `max*` field is zero or negative

Exceeding a pool’s total budget doesn’t produce an error. It sets capacity.overCommitted to true.

​List node pools on a cluster

​Create a node pool

​InputNodePool fields

​InputToleration fields

​Update a node pool

​Converge Deployments after a placement change

​Delete a node pool

​Errors

​See also

List node pools on a cluster

Create a node pool

InputNodePool fields

`InputToleration` fields

Update a node pool

Converge Deployments after a placement change

Delete a node pool

Errors

See also