Node Autoscaler Configuration Reference
Node Autoscaler (NA) configuration governs cluster takeover, node replacement, workload placement, and scheduling. It is distinct from Workload Autoscaler (WA), which adjusts container resources. Read NodePool and NodeClass settings alongside the cluster and workload settings below.
This is a read/reference guide, not an instruction to execute a rebalance. A recommendation must account for provider, onboarding phase, installed component versions, workload availability, and the current effective configuration. The current source’s field surface can be newer than a customer’s deployed runtime.
Choose the right read
| Question | MCP tool and result |
|---|---|
| Is optimization enabled, and is the cluster healthy? | get_cluster_overview for aggregate configuration/status and current health. |
| What NA configuration is saved? | get_node_autoscaler_configuration: data.rebalance, data.partOptimization, and data.workloadConfiguration. |
| What topology/cost does the optimizer propose? | get_node_optimization_plan: data.mode and data.plan. This read omits execution commands. A plan is not completed optimization or a guarantee of future savings. |
| Which pools/classes and instance candidates apply? | list_node_pools, get_node_pool, list_node_classes, get_node_class, and list_node_pool_candidates. |
| Why is a node not optimized or provisioning failing? | list_cluster_nodes (optimizationBlockedReason, status/message), list_controller_events, get_controller_event, and list_node_claim_events. |
| Which operational settings apply? | get_cluster_settings: data.settings, including maintenance, repair, decommission, cooldown, and supported provider-specific settings. |
| What scheduled actions are configured or have run? | list_node_pool_schedule_policies, list_node_pool_schedule_executions, list_scheduled_rebalance_policies, and list_scheduled_rebalance_executions. |
All cluster tools require organization_id and cluster_id; resource gets additionally need the resource name. Read status, warnings, sources, and observedAt in the common response envelope. A missing/failed source is not the same as a disabled feature, and stale reads are not proof of current runtime state. Continue paginated lists with their returned cursors and unchanged filters/sort until data.complete is true.
Universal clusters can use the Universal optimization-plan source but do not necessarily support managed NA configuration or provider NodePools. Check data.supported and data.reason rather than inventing an AWS-like configuration for them.
Cluster-level NA configuration
These paths are relative to get_node_autoscaler_configuration’s data object.
| Field | Value / source | Meaning |
|---|---|---|
supported, reason | Boolean and optional explanation. | Whether the managed configuration read applies to the provider. |
rebalance.enable | Boolean; read the saved cluster value. | Cluster NA enablement; not a guarantee that every pool is enabled or every node can be disrupted. |
rebalance.uploadConfig | Boolean, compatibility/configuration synchronization state. | Indicates configuration uploaded/synchronized from the Agent. This is not the workload-data privacy switch and does not authorize writes. |
rebalance.enableDiversityInstanceType | Boolean, opt-in according to saved configuration. | Cluster-level optimizer instance-type diversity control. It does not force a fixed market distribution or override unavailable capacity. |
rebalance.rebalanceType | all or node when returned by the applicable workflow. | Scope of optimization workflow; read together with selected nodes and onboarding phase. Do not infer the installation phase from this string alone. |
rebalance.state | Reported lifecycle state. | Current workflow state, not desired settings. May include Applying, FreezingNativeAutoscaling, LaunchingReplacements, Draining, Terminating, Failed, or Success on compatible agents. |
rebalance.message, rebalance.lastComponentsActiveTime | Message and optional timestamp. | Explanation and component freshness; missing time is unknown, not evidence of current activity. |
revision | Configuration fingerprint. | Useful to detect changed reads; not a Kubernetes resource version, permission, or write contract. |
Phase 1 provides observation/planning; managed Phase 2 additionally requires installed provisioning/runtime components and successful configuration. A saved enable flag or a successful plan does not itself prove Phase 2 readiness. Confirm component health, class readiness, current workflow status, and actual new-node behavior before treating takeover as complete.
Gradual optimization and force drain
| Field | Value / default | Meaning and risk |
|---|---|---|
partOptimization.nodes[] | Explicit source-node names; empty when no selection is stored. | Nodes selected for gradual optimization, not all eligible nodes or a percentage. |
partOptimization.forceDrain | Boolean; absent/new selection defaults false. | Requests stronger drain behavior in applicable workflows. It changes disruption risk and must not be enabled as a routine workaround for blocked workloads. |
See Gradual Optimization. Before selecting nodes, inspect blocked reasons, workload replicas, PodDisruptionBudgets, local data, replacement capacity, and class readiness. An empty selected list is not proof that no optimization opportunity exists.
Workload placement configuration
workloadConfiguration.workloads[] contains the NA workload records. These are not WA autoscaling policies and do not change CPU/memory requests by themselves.
| Field | Value / constraints | Interpretation |
|---|---|---|
name, namespace, type | Workload identity, such as Deployment or StatefulSet. | Match the exact workload and namespace; similarly named workloads are independent. |
replicas | Reported integer replica count. | Observed context, not a desired scale command in this configuration. |
rebalanceAble | Boolean; use returned effective configuration. | Whether the workload can participate in the NA rebalance workflow. Does not guarantee protection against all Kubernetes/cloud failures. |
spotFriendly | Boolean. | Eligibility for CloudPilot Spot scheduling; relevant when rebalanceable. Actual placement still depends on Pod and pool constraints. |
minNonSpotReplicas | Non-negative integer. | Requested non-Spot replica floor for Spot-friendly workloads. Requires sufficient compatible On-Demand capacity; it is not a total-replica setting or a guarantee against outages. |
New-workload default behavior depends on cluster settings and workload classification. get_cluster_settings.data.settings.enableWorkloadMinNonSpot controls the legacy minimum non-Spot default for newly discovered workloads; it is not equivalent to editing every existing workload’s explicit floor. Read actual records before proposing changes.
For Agent v1.21.0 or later, top-level Deployment/StatefulSet metadata can opt out; Pod metadata can further restrict behavior. The exact disabling value is the string "false":
| Metadata location / key | Meaning |
|---|---|
Workload metadata.labels["workload.cloudpilot.ai/spot-friendly"] | "false" opts out of Spot scheduling. |
Workload metadata.annotations["workload.cloudpilot.ai/rebalanceable"] | "false" opts out of rebalance. |
karpenter.sh/do-not-disrupt: "true" annotation | Additional disruption protection in applicable paths; not a guarantee against cloud termination or every forced/manual workflow. |
workload.cloudpilot.ai/min-nonspot label | Minimum non-Spot setting for metadata-based configuration; follow supported workload/version semantics in the guide. |
workload.cloudpilot.ai/diversity-instancetype: "true" label | Per-workload instance-type diversity, distinct from the cluster optimizer diversity flag. |
Pod-level opt-outs cannot re-enable a policy disabled on the owning workload. Do not put operational metadata into immutable workload selector labels. See Workload Configuration, Workload Diversity, and Spot Diversity.
For workload isolation, combine dedicated NodePool labels/taints with matching Pod node selectors/affinity and tolerations. Non-Spot floors and diversity do not override hard topology, architecture, GPU, disk, or affinity requirements. More diversity can require more capacity or prevent consolidation; confirm compatible candidates before tightening constraints.
Uploading and privacy
DISABLE_WORKLOAD_UPLOADING=true is an installation/runtime option, not rebalance.uploadConfig. Disabling workload uploading limits named workload details and Console workload-configuration features. Aggregated/UID-based data can still be uploaded; it is not a guarantee that no cluster data leaves the environment. Use supported labels/annotations for workload policy when named records are unavailable. See Disable Workload Uploading.
Do not interpret an empty named-workload result as no workloads until upload configuration, data freshness, permissions, and the source status have been checked.
Operational settings that affect NA
Read these from get_cluster_settings.data.settings; all are separate from the per-pool native disruption budget.
| Setting | Interpretation |
|---|---|
maintenanceEnabled | Observed maintenance switch. Follow the maintenance workflow; it is not a universal freeze of cloud/Kubernetes/manual actions. |
enableNodeRepair | Automatic repair control; repair has separate safety and trigger semantics from native consolidation. |
enableDiskMonitor | Disk-monitoring control; not a disk-size or PVC setting. |
enableNodePoolDecommission | Enables the supported drain-first pool deletion lifecycle; see NodePool lifecycle. |
disruptionCooldown | Cluster-default delay between compatible voluntary disruption batches; an explicit pool value can take precedence. |
awsSpotAllocationStrategy | AWS-only fleet Spot selection strategy; absent on other providers. It is distinct from spotFriendly and the set of allowed Spot instance types. |
preRunCommand, postRunCommand | Saved execution hooks in applicable workflows. Treat them as execution-sensitive configuration; do not include secrets in recommendations or assume they execute on every read. |
Availability and allowed values depend on provider/runtime version. Read the settings and existing operation state instead of assuming a blank default or applying a new release’s setting to an older cluster. See Operations and Settings for the complete settings and lifecycle reference, and Observability for diagnostic field interpretation.
Schedules are two different configuration types
NodePool scheduling enables provisioning or disables it and requests deletion of the pool’s NodeClaims. Scheduled Rebalance selects source nodes for an optimization workflow. Neither is a native NodePool budget cron window. NodePool scheduling is supported by the referenced AWS, GCP, and Azure implementations; verify the installed runtime before use.
NodePool enable/disable policy
Read list_node_pool_schedule_policies.data.items[]:
| Field | Meaning |
|---|---|
id, name, nodePoolName | Policy identity and target pool. |
enabled | Policy scheduler switch, not the pool’s current enabled state. |
timezone | Policy timezone; read the stored value. Unlike disruption budgets, this is configurable. |
disableCron, enableCron | Five-field action schedules evaluated in that timezone. |
nextDisableAt, nextEnableAt | Computed upcoming actions. |
lastRunAt, lastAction, lastStatus, lastMessage | Previous policy execution, not proof that the current pool still has the same state. |
Check list_node_pool_schedule_executions for per-run enable/disable action and status. Unlike manually setting a pool’s provisioning switch to false, a scheduled disable also marks backing nodes for schedule drain and deletes their NodeClaims. It can disrupt workloads; confirm workload tolerance, drain controls, decommission/maintenance conflicts, and spare compatible capacity first. deletedNodeClaimCount counts deletion requests, not completed node termination or a guaranteed zero-cost interval. Scheduled enable permits provisioning again; it does not instantly restore nodes or ready workloads.
Scheduled Rebalance policy
Read list_scheduled_rebalance_policies.data.items[]. Use only when supported by the installed server/Agent/provider; current source support must not be assumed to be deployed everywhere.
| Field | Meaning / constraints |
|---|---|
id, revision, name, enabled | Policy identity, configuration revision, display name, and scheduler switch. This numeric policy revision is distinct from MCP read fingerprints. |
cron, timezone | Five-field trigger schedule and timezone. |
scope.nodePoolName, .nodeNames[] | Optional pool and explicit source-node selection. |
scope.nodeSelectorTerms[], .excludeNodeSelectorTerms[] | Label selectors with matchExpressions[]: key, operator, and appropriate values; supported operators In, NotIn, Exists, DoesNotExist. |
scope.excludeNodeNames[], .capacityTypes[] | Exclusions and purchase-option filters. |
nodeConstraints.minAgeSeconds | Minimum source-node age, in seconds. |
nodeConstraints.maxNodes, .minClusterSize | Per-run selection bound and minimum cluster-size guard. Do not interpret these as native disruption budgets. |
selectionOrder | oldest_first, newest_first, name_asc, or lowest_utilization_first, when supported. |
forceDrain | Explicit disruption-risk choice, normally false; do not enable simply to make a schedule succeed. |
nextRunAt, lastRunAt, lastStatus, lastMessage | Computed timing and previous outcome. |
Read list_scheduled_rebalance_executions for selected nodes, timing, outcome, and skip/failure reasons. A triggered execution only confirms handoff to the workflow, not successful workload migration. Validate the subsequent NA workflow and node events.
Recommended rollout patterns
Start with one workload and a small source-node set
Read overview, effective workload placement, the source nodes’ blocked reasons, and the plan. Keep replacement On-Demand capacity compatible with the workload. Start with non-critical replicated workloads, ordinary drain behavior, and a small gradual-optimization selection. Validate node Ready status, Pod readiness, application availability, and actual cost/resource history before expanding. Do not infer real savings from a plan alone.
Protect a critical service while using Spot elsewhere
For critical workloads, opt out of Spot or retain an explicit non-Spot floor and enough compatible On-Demand capacity. Check actual replica count, PDBs, and selectors; a floor greater than available replicas/capacity does not manufacture availability. Apply Spot eligibility first to interruption-tolerant workloads, then compare actual placement and disruption events. The rollback is to restore workload/pool placement settings and verify replacement capacity, not blindly force-drain Spot nodes.
Add a recurring maintenance or optimization policy
First distinguish the desired action: pause native voluntary disruption (budget), schedule pool shutdown/re-enablement (NodePool schedule), or select nodes for migration (Scheduled Rebalance). Use the correct timezone rules, narrow selection, and ordinary drain behavior. Confirm next-run timestamps and review the first execution plus downstream controller events. Disable the policy and inspect in-flight work separately if the result is unexpected; disabling a future schedule does not necessarily cancel work already triggered.