Autoscaling a cluster

This page shows you how to autoscale your Standard Google Kubernetes Engine (GKE)clusters. To learn about how the cluster autoscaler works, refer toCluster autoscaler.

With Autopilot clusters, you don't need to worry aboutprovisioning nodes or managing node pools because node pools areautomaticallyprovisioned throughnode auto-provisioning,and areautomatically scaledto meet the requirements of your workloads.

Using the cluster autoscaler

Note: Enabling or disabling cluster autoscaling might cause the control plane torestart, which takes several minutes to complete. Once autoscaling is enabledfor at least one node pool, further changes to the cluster autoscalerconfiguration does not cause the control plane to restart until autoscaling isdisabled for the last node pool. However, autoscaling might still take up to oneminute for changes to propagate after the operation completes.

The following sections explain how to use cluster autoscaler.

Creating a cluster with autoscaling

You can create a cluster with autoscaling enabled using the Google Cloud CLIor the Google Cloud console.

gcloud

To create a cluster with autoscaling enabled, use the--enable-autoscalingflag and specify--min-nodes and--max-nodes:

gcloudcontainerclusterscreateCLUSTER_NAME\--enable-autoscaling\--num-nodesNUM_NODES\--min-nodesMIN_NODES\--max-nodesMAX_NODES\--location=CONTROL_PLANE_LOCATION

Replace the following:

Example: Creating a cluster with node autoscaling enabled and min and max nodes

The following command creates a cluster with 90 nodes, or 30 nodes ineach of the 3 zones present in the region. Node autoscaling is enabled andresizes the number of nodes based oncluster load.The cluster autoscaler can reduce the size of the default node pool to 15nodes or increase the node pool to a maximum of 50 nodes per zone.

gcloud container clusters create my-cluster --enable-autoscaling \    --num-nodes=30 \    --min-nodes=15 --max-nodes=50 \    --location=us-central

Example: Creating a cluster with node autoscaling enabled and total nodes

The following command creates a cluster with 30 nodes, or 10 nodes in eachof the 3 zones present in the region. Node autoscaling is enabled andresizes the number of nodes based oncluster load.In this example, the total size of the cluster can be between 10 and 60nodes, regardless of spreading between zones.

gcloud container clusters create my-cluster --enable-autoscaling \    --num-nodes 10 \    --location us-central1 \    --total-min-nodes 10  --total-max-nodes 60

Console

To create a new cluster in which the default node pool has autoscalingenabled:

  1. In the Google Cloud console, go to theCreate a Kubernetes cluster page.

    Go to Create a Kubernetes cluster

  2. Configure your cluster as desired.

  3. From the navigation pane, underNode Pools, clickdefault-pool.

  4. Select theEnable autoscaling checkbox.

  5. Change the values of theMinimum number of nodes andMaximum number of nodesfields as desired.

  6. ClickCreate.

Adding a node pool with autoscaling

You can create a node pool with autoscaling enabled using thegcloud CLI or the Google Cloud console.

gcloud

To add a node pool with autoscaling to an existing cluster, use thefollowing command:

gcloudcontainernode-poolscreatePOOL_NAME\--cluster=CLUSTER_NAME\--enable-autoscaling\--min-nodes=MIN_NODES\--max-nodes=MAX_NODES\--location=CONTROL_PLANE_LOCATION

Replace the following:

  • POOL_NAME: the name of the desired node pool.
  • CLUSTER_NAME: the name of the cluster in which thenode pool is created.
  • MIN_NODES: the minimum number of nodes toautomatically scale for the specified node pool per zone. To specify theminimum number of nodes for the entire node pool in GKEversions 1.24 and later, use--total-min-nodes. The flags--total-min-nodes and--total-max-nodes are mutually exclusive withthe flags--min-nodes and--max-nodes.
  • MAX_NODES: the maximum number of nodes toautomatically scale for the specified node pool per zone. To specify themaximum number of nodes for the entire node pool in GKEversions 1.24 and later, use--total-max-nodes. The flags--total-min-nodes and--total-max-nodes are mutually exclusive withthe flags--min-nodes and--max-nodes.
  • CONTROL_PLANE_LOCATION: the Compute Enginelocation of the control plane of yourcluster. Provide a region for regional clusters, or a zone for zonal clusters.

Example: Adding a node pool with node autoscaling enabled

The following command creates a node pool with node autoscaling that scalesthe node pool to a maximum of 5 nodes and a minimum of 1 node:

gcloud container node-pools create my-node-pool \    --cluster my-cluster \    --enable-autoscaling \    --min-nodes 1 --max-nodes 5 \    --location us-central1-c

Console

To add a node pool with autoscaling to an existing cluster:

  1. Go to theGoogle Kubernetes Engine page in the Google Cloud console.

    Go to Google Kubernetes Engine

  2. In the cluster list, click the name of the cluster you want to modify.

  3. ClickAdd Node Pool.

  4. Configure the node pool as desired.

  5. UnderSize, select theEnable autoscaling checkbox.

  6. Change the values of theMinimum number of nodes andMaximum numberof nodes fields as desired.

  7. ClickCreate.

Enabling autoscaling for an existing node pool

You can enable autoscaling for an existing node pool using thegcloud CLI or the Google Cloud console.

gcloud

To enable autoscaling for an existing node pool, use the followingcommand:

gcloudcontainerclustersupdateCLUSTER_NAME\--enable-autoscaling\--node-pool=POOL_NAME\--min-nodes=MIN_NODES\--max-nodes=MAX_NODES\--location=CONTROL_PLANE_LOCATION

Replace the following:

  • CLUSTER_NAME: the name of the cluster to update.
  • POOL_NAME: the name of the desired node pool. Ifyou have only one node pool, supplydefault-pool as the value.
  • MIN_NODES: the minimum number of nodes toautomatically scale for the specified node pool per zone. To specify theminimum number of nodes for the entire node pool in GKEversions 1.24 and later, use--total-min-nodes. The flags--total-min-nodes and--total-max-nodes are mutually exclusive withthe flags--min-nodes and--max-nodes.
  • MAX_NODES: the maximum number of nodes toautomatically scale for the specified node pool per zone. To specify themaximum number of nodes for the entire node pool in GKEversions 1.24 and later, use--total-max-nodes. The flags--total-min-nodes and--total-max-nodes are mutually exclusive withthe flags--min-nodes and--max-nodes.
  • CONTROL_PLANE_LOCATION: the Compute Enginelocation of the control plane of yourcluster. Provide a region for regional clusters, or a zone for zonal clusters.

Console

To enable autoscaling for an existing node pool:

  1. Go to theGoogle Kubernetes Engine page in the Google Cloud console.

    Go to Google Kubernetes Engine

  2. In the cluster list, click the name of the cluster you want to modify.

  3. Click theNodes tab.

  4. UnderNode Pools, click the name of the node pool you want to modify,then clickEdit.

  5. UnderSize, select theEnable autoscaling checkbox.

  6. Change the values of theMinimum number of nodes andMaximum numberof nodes fields as desired.

  7. ClickSave.

Verifying that autoscaling for the existing node pool is enabled

You verify that your cluster is using autoscaling with the Google Cloud CLIor the Google Cloud console.

gcloud

Describe the node pools in the cluster:

gcloudcontainernode-poolsdescribeNODE_POOL_NAME--cluster=CLUSTER_NAME|grepautoscaling-A1

Replace the following:

  • POOL_NAME: the name of the new node pool that youchoose.
  • CLUSTER_NAME: the name of the cluster.

If autoscaling is enabled, the output is similar to the following:

autoscaling:  enabled: true

Console

  1. Go to theGoogle Kubernetes Engine page in the Google Cloud console.

    Go to Google Kubernetes Engine

  2. In the cluster list, click the name of the cluster you want to verify.

  3. Click theNodes tab.

  4. UnderNode Pools, verify that node poolAutoscalling state.

Creating a node pool that prioritizes optimization of unused reservations

Note: Starting in GKE version 1.27, cluster autoscaler alwaysconsidersreservationswhen making the scale-up decisions, regardless of the used location policy.

You can use the--location_policy=ANY flag when you create a node pool toinstruct the cluster autoscaler toprioritize utilization of unused reservations:

gcloudcontainernode-poolscreatePOOL_NAME\--cluster=CLUSTER_NAME\--location_policy=ANY

Replace the following:

  • POOL_NAME: the name of the new node pool that youchoose.
  • CLUSTER_NAME: the name of the cluster.

Disabling autoscaling for an existing node pool

You can disable autoscaling for an existing node pool using thegcloud CLI or the Google Cloud console.

gcloud

To disable autoscaling for a specific node pool, use the--no-enable-autoscaling flag:

gcloudcontainerclustersupdateCLUSTER_NAME\--no-enable-autoscaling\--node-pool=POOL_NAME\--location=CONTROL_PLANE_LOCATION

Replace the following:

  • CLUSTER_NAME: the name of the cluster to update.
  • POOL_NAME: the name of the desired node pool.
  • CONTROL_PLANE_LOCATION: the Compute Enginelocation of the control plane of yourcluster. Provide a region for regional clusters, or a zone for zonal clusters.

The cluster size is fixed at the cluster's current default node pool size,which can bemanually updated.

Console

To disable autoscaling for a specific node pool:

  1. Go to theGoogle Kubernetes Engine page in the Google Cloud console.

    Go to Google Kubernetes Engine

  2. In the cluster list, click the name of the cluster you want to modify.

  3. Click theNodes tab.

  4. UnderNode Pools, click the name of the node pool you want to modify, then clickEdit.

  5. UnderSize, clear theEnable autoscaling checkbox.

  6. ClickSave.

Resizing a node pool

For clusters with autoscaling enabled, the cluster autoscaler automaticallyresizes node pools within the boundaries specified by either the minimum size(--min-nodes) and maximum size (--max-nodes) values or the minimum totalsize (--total-min-nodes) and maximum total size (--total-max-nodes). Theseflags are mutually exclusive. You can't manually resize a node pool by changingthese values.

If you want to manually resize a node pool in your cluster that has autoscalingenabled, perform the following:

  1. Disable autoscaling on the node pool.
  2. Manually resize the cluster.
  3. Re-enable autoscaling and specify the minimum and maximum node pool size.

Preventing Pods scheduling on selected nodes

You can usestartup orstatus taints to prevent Pods scheduling on selected nodes, depending on the use case.

This feature is available in GKE in version 1.28 and later.

Startup taints

Usestartup taints when there is an operation that has to complete before any Pods can run on the node. For example, Pods shouldn't run until the drivers installation on node finishes.

Cluster autoscaler treats nodes tainted withstartup taints as unready, but taken into account during scale up logic, assuming they will become ready shortly. We recommend that you don't apply thestartup taints to the nodes for an extended period of time. The cluster autoscalermight stop working if a substantial number of nodes are tainted with startup taints, which means that they are unready. In this case, GKE doesn't scale up the cluster because even new nodes don't become ready. Therefore, GKE treats this cluster as broken.

Startup taints are defined as all taints with the prefixstartup-taint.cluster-autoscaler.kubernetes.io/

Status taints

Usestatus taints when GKE shouldn't use a given node to run Pods.

Cluster autoscaler treats nodes tainted withstatus taints as ready, but ignores them during scale up logic. Even though the tainted node is ready, no Pods should run. If more resources are needed by the Pods, GKE scales up the cluster and ignores the tainted nodes.

Status taints are defined as all taints with the prefixstatus-taint.cluster-autoscaler.kubernetes.io/

Ignore taints

Deprecated: Ignore taints are now deprecated and treated as startup taints.

Ignore taints are defined as all taints with the prefixignore-taint.cluster-autoscaler.kubernetes.io/

Troubleshooting

For troubleshooting advice, see the following pages:

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.