NodePool Field Reference

A NodePool defines which capacity CloudPilot can create and which Pods can use it. A NodeClass defines the provider-specific machine configuration. Pool constraints, Pod scheduling requirements, available cloud capacity, and the referenced NodeClass must all be compatible.

This reference covers the Console’s visual field groups and their read representation. Raw YAML is validated by the installed provider CRD; the existence of a field in another provider or newer release does not make it available on your cluster. Add-ons require compatible server, Agent, provider, and node images.

Read the effective configuration

Use list_node_pools for discovery and get_node_pool with organization_id, cluster_id, and name for details. Set default: true instead of name to inspect the provider default. Defaults returned for this cluster are more authoritative than examples or a blank form.

The MCP result’s data.configuration contains the CloudPilot pool object. All field paths below are relative to that object. For example, nodePoolSpec.weight means data.configuration.nodePoolSpec.weight; the native Kubernetes equivalent is NodePool.spec.weight. A list with detail: "summary" deliberately omits configuration; use the named get or detail: "full". Continue list cursors until data.complete is true.

The pool read does not currently expose the full native NodePool.status. Use NodeClass readiness, instance candidates, node health, controller events, and NodeClaim events together; an enabled pool can still be unable to provision.

Identity, activation, and scheduling

AWS reads may also contain the compatibility wrapper nodePoolAnnotation. It is not the same path as template annotations; preserve existing compatibility metadata rather than moving it between these fields.

Capacity and placement requirements

The array nodePoolSpec.template.spec.requirements[] contains key, operator, and, where required, values. Requirements are combined, not independent preferences. The common operators are In, NotIn, Exists, DoesNotExist, Gt, and Lt; numeric comparisons use one integer string and are exclusive. Provider-specific minValues is an advanced, version-dependent diversity constraint, not a minimum node count.

Azure also exposes SKU series through karpenter.azure.com/sku-series. GPU category, model, count, accelerator memory, hypervisor, and local-storage constraints are provider-specific native requirements; preserve existing requirements when editing a visual field. The general preset excludes GPU instances and can exclude other incompatible families, so an empty family selector does not mean every cloud instance is eligible.

The general-purpose preset’s upper bounds are CPU Lt: ["17"] and memory Lt: ["32769"]: at most 16 cores and 32768 MiB. The current editor labels these inputs Minimum (exclusive) and Maximum (exclusive). Entering 16 as the maximum excludes 16-core instances. A cleared range input removes that bound; it is not a zero-resource machine.

Use list_node_pool_candidates with node_pool_name to inspect compatible instance types. Check data.status, reason, and computedAt before treating an empty candidate list as proof that nothing matches. Candidates are not a reservation or a guarantee of real-time cloud capacity.

Pool-wide limits

Limits do not proactively shrink a pool already above a reduced cap. Provisioning is eventually consistent, so do not use a pool limit as an exact spending or instantaneous safety boundary.

Lifecycle and disruption

Each budget has nodes (count string or percentage), optional reasons (Empty, Underutilized, Drifted), and optional paired schedule and duration. Budget cron windows use UTC, not a configurable timezone. Omit reasons for all reasons; do not use an empty list. Multiple active matching budgets use the most restrictive allowance. See the budget guide for arithmetic and examples.

Budgets do not govern every deletion path: scheduled rebalance, expiration, repair, cloud interruption, and manual deletion have separate controls. A zero native drift budget is not a global disruption freeze.

lifecycleState (active or decommissioning) and decommissionRequestedAt are observed CloudPilot lifecycle fields, not knobs to edit directly. With supported Phase 2 NodePool decommission enabled in cluster settings, deletion disables provisioning and waits for backing capacity to drain. Verify replacement pools can accept pinned workloads before deletion; see safe pool deletion.

CloudPilot add-ons

These are wrapper fields alongside nodePoolSpec, not native NodePool.spec properties. A newer Console may expose them before an older cluster has the required runtime. Verify installed components before recommending activation.

For batch configuration, omitting jobNodePoolOptimization on update preserves the current configuration; an empty object clears it. This read reference does not add MCP writes. Follow Batch workload optimization for supported versions, pool isolation, soft-drain behavior, and hard-drain differences.

Safe starting scenarios

Introduce Spot without moving every workload

1. Keep a compatible On-Demand pool enabled. Start with interruptible, replicated workloads and allow suitable Spot families and zones in a separate pool.
2. Check workload spotFriendly and minNonSpotReplicas in NA configuration; a Spot-capable NodePool alone does not override workload opt-outs or affinity.
3. Read candidates, class readiness, the optimization plan, then node/controller events after a limited rollout. Watch pending Pods and application availability; revert placement requirements or disable new provisioning if capacity is unsuitable.

Isolate a dedicated workload or batch pool

Use a dedicated node label plus a NoSchedule taint, and give only the target Pods a matching selector/affinity and toleration. A taint alone does not keep target Pods off other pools. For batch, begin with a small active-node target and short delay; test burst completion latency before expanding. Do not mix ordinary services into a pool whose packing and soft-drain behavior assumes run-to-completion work.

Slow native replacements

Preserve an always-active budget and add a stricter Drifted allowance, then tune cooldown separately. Confirm replicas, PodDisruptionBudgets, replacement candidates, and class readiness first. Validate actual controller events rather than assuming a saved configuration already replaced existing machines.