AKS Cluster Autoscaler: Configuration Guide A traffic spike hits, new pods land in Pending, and nothing schedules because every node is full. Or the opposite: the spike ends and half your nodes sit idle, billing by the hour. Both problems come from the same place, a node count that doesn't track real scheduling demand.

The AKS-managed Cluster Autoscaler fixes both, but only if you set it up with care. This guide covers enabling it with Azure CLI, choosing node-pool boundaries, tuning the profile, validating behavior, and troubleshooting when nodes don't move.

Key Takeaways

  • The Cluster Autoscaler adds or removes nodes based on pod scheduling, not live CPU load.
  • HPA or KEDA creates pod demand; the autoscaler supplies the nodes.
  • Min/max, requests, quotas, taints, and PodDisruptionBudgets all shape outcomes.
  • Verify decisions with status data, events, and Azure Monitor before changing production.

What Is the AKS Cluster Autoscaler?

The Cluster Autoscaler adjusts the number of VM nodes in an AKS node pool. AKS runs it in the managed control plane, so you don't deploy or patch a controller yourself.

Scale-up flow

  1. A pod goes Pending because no node has enough allocatable resources.
  2. The autoscaler simulates whether adding a node to an eligible pool would let the pod schedule.
  3. If so, it raises that pool's size within your max-count, and AKS requests the VM from Azure.

Three-step AKS cluster autoscaler scale-up flow for pending pods

An unschedulable pod doesn't guarantee a scale-up. If a new node still wouldn't satisfy the pod's constraints, nothing happens.

Scale-down flow

The autoscaler looks for nodes with low requested utilization, waits until they've been unneeded long enough, and checks that their pods can reschedule safely.

AKS defaults:

  • Utilization threshold of 0.5
  • Unneeded time of 10 minutes
  • Post-scale-up delay of 10 minutes

These are not deletion deadlines.

Requests, not usage

The autoscaler reads resource requests, not observed utilization. The threshold uses the larger of CPU requests over allocatable CPU and memory requests over allocatable memory.

A pod requesting 2 CPUs but using 0.1 still occupies 2 CPUs in the autoscaler's math. Inaccurate requests lead to wasted nodes or Pending pods.

Boundaries to know

  • Node-pool min and max counts
  • Subscription quotas (regional and VM-family vCPU)
  • VM size and zone capacity, which quota doesn't guarantee
  • Provisioning delays of several minutes
  • Pods that can't be evicted

How the AKS Cluster Autoscaler Fits with Other Autoscalers

Microsoft's scaling overview separates these tools by what each one controls:

Component Controls
Cluster Autoscaler Node count in predefined pools
HPA Pod replicas
VPA Pod CPU/memory requests
KEDA add-on Event-driven replicas (uses HPA internally)
Node Auto-Provisioning Nodes chosen for pending pods, including VM SKU

A two-layer design

HPA or KEDA adds replicas. If nodes are full, those replicas go Pending, and the Cluster Autoscaler adds nodes. The catch is timing: pods scale in seconds, nodes take minutes. Expect a window of Pending pods during sharp spikes, and size baseline capacity accordingly.

Two-layer HPA KEDA and AKS cluster autoscaler scaling design

Don't point an HPA and a KEDA ScaledObject at the same workload. They will fight.

Plan Your AKS Autoscaler Configuration

Prerequisites

  • An AKS cluster using Virtual Machine Scale Sets and a Standard Load Balancer
  • Azure CLI 2.0.76 or later (check with az --version)
  • The right subscription and resource group selected
  • Contributor or Owner on the resource group
  • A valid kubectl context

System pools need Linux nodes, with a 2-node minimum and 3 recommended. The CLI accepts a system-pool min-count of 1, which conflicts with that guidance, so follow the system-pool guide.

Inventory your node pools

Before touching anything, record for each pool:

  • VM size and current node count
  • Workload purpose
  • Labels, taints, and tolerations
  • Availability requirements
  • Whether this pool should autoscale at all

Choose min and max deliberately

Pull historical demand rather than guessing. Set min-count to cover baseline load plus the disruption you can tolerate while new nodes boot. Set max-count to what quota, regional VM availability, and budget allow.

Limits to remember: 1,000 nodes per VMSS pool, 5,000 per cluster, 100 pools per cluster. Check vCPU headroom with az vm list-usage.

Configure Cluster Autoscaler in AKS

Names and counts below are example values. Confirm flags against current Microsoft documentation, since the CLI changes.

Create a new cluster

az aks create -g RG -n AKS --node-count 2 \
  --vm-set-type VirtualMachineScaleSets \
  --load-balancer-sku standard \
  --enable-cluster-autoscaler --min-count 2 --max-count 5 \
  --generate-ssh-keys

Enable on an existing node pool

az aks nodepool update -g RG --cluster-name AKS -n POOL \
  --enable-cluster-autoscaler --min-count 2 --max-count 5

Inspect before changing

az aks nodepool list -g RG --cluster-name AKS -o table
az aks nodepool show -g RG --cluster-name AKS -n POOL

In the portal, go to your AKS resource, then Settings > Node pools. You'll see node counts and autoscale status.

Update bounds or disable

az aks nodepool update -g RG --cluster-name AKS -n POOL \
  --update-cluster-autoscaler --min-count 2 --max-count 10

az aks nodepool update -g RG --cluster-name AKS -n POOL \
  --disable-cluster-autoscaler

Disabling returns the pool to manual node counts. --update-cluster-autoscaler isn't supported on VirtualMachines pools, so these examples target VMSS.

Multiple node pools

Enable autoscaling per pool with nodepool update. Which pool grows depends on whether the Pending pod matches that pool:

  • Node selectors must match pool labels
  • Tolerations must match pool taints
  • Resource requests must fit the pool's VM size

A GPU workload without the right toleration will never trigger the GPU pool.

Skip the legacy guides

Older tutorials deploy a separate autoscaler controller, hand-create Azure credentials, or use preview extensions. Skip them. AKS runs the autoscaler for you.

Never enable or edit autoscaling on the underlying VMSS. Keep it on Manual scale. Custom VMSS autoscale is unsupported and causes failures.

Tune Scaling Behaviour for Production

Tune Scaling Behavior for Production

The cluster autoscaler profile holds settings shared by all autoscaler-enabled pools. It applies immediately.

az aks update -g RG -n AKS --cluster-autoscaler-profile scan-interval=30s

Settings that matter most

Key AKS default
scan-interval 10s
scale-down-delay-after-add 10m
scale-down-unneeded-time 10m
scale-down-unready-time 20m
scale-down-utilization-threshold 0.5
max-graceful-termination-sec 600
max-node-provision-time 15m
balance-similar-node-groups false
expander random
skip-nodes-with-local-storage false
skip-nodes-with-system-pods true

Shorter delays cut costs but raise churn and disruption. Longer ones protect availability but keep idle nodes around. The full list has 20 keys, including DaemonSet eviction settings that are GA from API version 2024-05-01. Check the supported list for your AKS version before setting anything.

Choosing which pool scales

The expander decides when several pools could fit a pod. Options are random, most-pods, least-waste, and priority. Use priority to prefer cheaper pools. Microsoft's AKS engineering team shows a layout that prefers Spot with on-demand fallback. Turn on balance-similar-node-groups when you run identical pools across zones.

AKS autoscaler expander options for choosing eligible node pools

Scale-down blockers

  • Restrictive PodDisruptionBudgets
  • Local storage (hostPath, non-memory emptyDir) when skipping applies
  • Pods without a controller
  • kube-system pods (non-DaemonSet)
  • Affinity, anti-affinity, or topology rules that no other node satisfies
  • The annotation cluster-autoscaler.kubernetes.io/safe-to-evict: "false"
  • Missing resource requests

Production safeguards

  • Set a realistic max-count and confirm quota first
  • Test profile changes off-peak
  • Watch Pending pods after each change
  • Avoid aggressive scale-down that conflicts with availability targets

Where storage fits

The autoscaler manages compute nodes, not disks. Azure managed disks can't be shrunk, and billing follows provisioned capacity rather than used space. Lucidity complements the autoscaler here by expanding and shrinking Azure block storage in real time without application code changes, with cost reductions of up to 70%.

Verify, Monitor, and Troubleshoot Autoscaling

Run a controlled test

  1. Deploy a workload with realistic CPU and memory requests.
  2. Scale replicas until some pods go Pending.
  3. Watch nodes join with kubectl get nodes.
  4. Scale back down and confirm nodes leave only after the unneeded-time and delay timers expire.

Four-step AKS cluster autoscaler controlled testing workflow

Read status and events

kubectl get configmap -n kube-system cluster-autoscaler-status -o yaml
kubectl get events --field-selector source=cluster-autoscaler,reason=NotTriggerScaleUp
kubectl get events --field-selector source=cluster-autoscaler,type=Warning

Fields worth reading in the status ConfigMap:

  • Health: Healthy or Unhealthy
  • ScaleUp: Needed, NotNeeded, InProgress, NoActivity, or Backoff
  • ScaleDown: CandidatesPresent or NoCandidates
  • CloudProviderTarget: the size the autoscaler requested from Azure
  • LastProbeTime and LastTransitionTime: when it last checked and when the state began

Also run kubectl describe pod on a Pending pod. The events usually name the constraint.

Azure-side signals

In the portal, open Node pools and check Autoscale events, Autoscale warnings, and Scale-up not triggered.

For deeper analysis, enable the cluster-autoscaler diagnostic category and query it:

AzureDiagnostics | where Category == "cluster-autoscaler"

Azure Monitor offers preview metrics such as cluster_autoscaler_unschedulable_pods_count and cluster_autoscaler_unneeded_nodes_count. For managed Prometheus, enable the cluster-autoscaler target under control plane metrics, since it's off by default.

Common symptoms

Symptom Check
No scale-up Taints, affinity, volume constraints, pool max, subnet IPs, quota, VM capacity
No scale-down Pool min, timers, PDBs, eviction blockers, resource locks
Repeated failed scale-ups Backoff can delay retries up to 30 minutes; disable and re-enable to reset
"Failed to fix node group sizes" Disable and re-enable the autoscaler, per Microsoft's troubleshooting guide

AKS cluster autoscaler troubleshooting symptoms and diagnostic checks

Frequently Asked Questions

What is the AKS cluster autoscaler?

A managed AKS feature that adjusts node counts in a pool based on pod scheduling demand and node utilization. It works at the node level, unlike pod-level autoscalers.

What is the difference between HPA and the AKS cluster autoscaler?

HPA changes pod replicas; the Cluster Autoscaler changes node capacity. Together, HPA creates pods and the autoscaler adds nodes to host them.

What is Azure Autoscale and how does it work with AKS?

Azure Monitor autoscale uses metric or schedule rules for resources like VMSS and App Service. For AKS nodes, use the AKS autoscaler instead; custom VMSS autoscale is unsupported.

How do I enable the AKS cluster autoscaler on an existing node pool?

Run az aks nodepool update --enable-cluster-autoscaler --min-count N --max-count M with your resource group, cluster, and pool name. Confirm permissions and supported configuration first.

What do min-count and max-count mean?

They are the lower and upper node limits for a pool. Set max-count with workload peaks, quota, and budget in mind, because it caps scale-up.

Why is my cluster autoscaler not adding or removing nodes?

Common causes are scheduling constraints, inaccurate requests, pool limits, quota or capacity gaps, and PDBs. Check the status ConfigMap and autoscaler events to find which one applies.