Add and manage node pools

This page shows you how to add and perform operations on node pools running your Google Kubernetes Engine (GKE) Standard clusters. To learn about how node pools work, refer to About node pools.

Clusters can perform operations, such as node auto-provisioning, on multiple node pools in parallel. You can manually create, update, or delete a node pool while another node pool is already being created, updated, or deleted.

These instructions don't apply to Autopilot clusters, where GKE manages the nodes, and there are no node pools for you to manage. To learn more, see the Autopilot overview.

Before you begin

Before you start, make sure you have performed the following tasks:

  • Enable the Google Kubernetes Engine API.
    • Enable Google Kubernetes Engine API
  • If you want to use the Google Cloud CLI for this task, install and then initialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running gcloud components update.

Add a node pool to a Standard cluster

You can add a new node pool to a GKE Standard cluster using the gcloud CLI, the Google Cloud console, or Terraform. GKE also supports node auto-provisioning, which automatically manages the node pools in your cluster based on scaling requirements.

Best practice:

Create and use a minimally-privileged Identity and Access Management (IAM) service account for your node pools to use instead of the Compute Engine default service account. For instructions to create a minimally-privileged service account, refer to Hardening your cluster's security.

gcloud

To create a node pool, run the gcloud container node-pools create command:

gcloud container node-pools create POOL_NAME \
    --cluster CLUSTER_NAME \
    --service-account SERVICE_ACCOUNT

Replace the following:

  • POOL_NAME: the name of the new node pool.
  • CLUSTER_NAME: the name of your existing cluster.
  • SERVICE_ACCOUNT: the name of the IAM service account for your nodes to use. If omitted, the node pool uses the Compute Engine default service account.
  • To provision nodes through private IP addresses, add the --enable-private-nodes flag. You can use this flag in public clusters that use Private Service Connect. To check if your cluster uses Private Service Connect, see Clusters with Private Service Connect.

For a full list of optional flags you can specify, refer to the gcloud container node-pools create documentation.

The output is similar to the following:

Creating node pool POOL_NAME...done.
Created [https://container.googleapis.com/v1/projects/PROJECT_ID/zones/us-central1/clusters/CLUSTER_NAME/nodePools/POOL_NAME].
NAME: POOL_NAME
MACHINE_TYPE: e2-medium
DISK_SIZE_GB: 100
NODE_VERSION: 1.21.5-gke.1302

In this output, you see details about the node pool, such as the machine type and GKE version running on the nodes.

Occasionally, the node pool is created successfully but the gcloud command times out instead of reporting the status from the server. To check the status of all node pools, including those not yet fully provisioned, use the following command:

gcloud container node-pools list --cluster CLUSTER_NAME

Console

To add a node pool to an existing Standard cluster, perform the following steps:

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

    Go to Google Kubernetes Engine

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

  3. Click Add node pool.

  4. Configure your node pool.

  5. In the navigation menu, click Security.

  6. In the Service account drop-down menu, select the IAM service account for your node pool to use. By default, the node pool uses the Compute Engine default service account.

  7. Click Create to add the node pool.

Terraform

To add a node pool to an existing Standard cluster using Terraform, refer to the following example:

resource "google_container_node_pool" "default" {
  name    = "gke-standard-regional-node-pool"
  cluster = google_container_cluster.default.name

  node_config {
    service_account = google_service_account.default.email
  }
}

To learn more about using Terraform, see Terraform support for GKE.

View node pools in a Standard cluster

gcloud

To list all the node pools of a Standard cluster, run the gcloud container node-pools list command:

gcloud container node-pools list --cluster CLUSTER_NAME

To view details about a specific node pool, run the gcloud container node-pools describe command:

gcloud container node-pools describe POOL_NAME \
    --cluster CLUSTER_NAME

Replace the following:

  • CLUSTER_NAME: the name of the cluster.
  • POOL_NAME: the name of the node pool to view.

Console

To view node pools for a Standard cluster, perform the following steps:

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

    Go to Google Kubernetes Engine

  2. In the cluster list, click the name of the Standard cluster.

  3. Click the Nodes tab.

  4. Under Node Pools, click the name of the node pool you want to view.

Scale a node pool

You can scale your node pools up or down to optimize for performance and cost. With GKE Standard node pools, you can scale a node pool horizontally by changing the number of nodes in the node pool, or scale a node pool vertically by changing the machine attribute configuration of the nodes.

Horizontally scale by changing the node count

gcloud

To resize a cluster's node pools, run the gcloud container clusters resize command:

gcloud container clusters resize CLUSTER_NAME \
    --node-pool POOL_NAME \
    --num-nodes NUM_NODES

Replace the following:

  • CLUSTER_NAME: the name of the cluster to resize.
  • POOL_NAME: the name of the node pool to resize.
  • NUM_NODES: the number of nodes in the pool in a zonal cluster. If you use multi-zonal or regional clusters, NUM_NODES is the number of nodes for each zone the node pool is in.

Repeat this command for each node pool. If your cluster has only one node pool, omit the --node-pool flag.

Console

To resize a cluster's node pools, perform the following steps:

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

    Go to Google Kubernetes Engine

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

  3. Click the Nodes tab.

  4. In the Node Pools section, click the name of the node pool that you want to resize.

  5. Click Resize.

  6. In the Number of nodes field, enter how many nodes that you want in the node pool, and then click Resize.

  7. Repeat for each node pool as needed.

Vertically scale by changing the node machine attributes

You can modify the node pool's configured machine type, disk type, and disk size.

When you edit one or more of these machine attributes, GKE updates the nodes to the new configuration using the upgrade strategy configured for the node pool. If you configure the blue-green upgrade strategy you can migrate the workloads from the original nodes to the new nodes while being able to roll back the original nodes if the migration fails. Inspect the upgrade settings of the node pool to ensure that the configured strategy is how you want your nodes to be updated.

Update at least one of the highlighted machine attributes in the following command:

gcloud container node-pools update POOL_NAME \
    --cluster CLUSTER_NAME \
    --machine-type MACHINE_TYPE \
    --disk-type DISK_TYPE \
    --disk-size DISK_SIZE

Omit any flags for machine attributes that you don't want to change. However, you must use at least one machine attribute flag, as the command otherwise fails.

Replace the following:

  • POOL_NAME: the name of the node pool to resize.
  • CLUSTER_NAME: the name of the cluster to resize.
  • MACHINE_TYPE: the type of machine to use for nodes. To learn more, see gcloud container node-pools update.
  • DISK_TYPE: the type of the node VM boot disk, must be one of pd-standard, pd-ssd, pd-balanced.
  • DISK_SIZE: the size for node VM boot disks in GB. Defaults to 100GB.

Migrate workloads between node pools

If you want to migrate workloads between one node pool and another node pool, follow the instructions to migrate workloads between node pools. For example, you can use these instructions if you're replacing an existing node pool with a new node pool and you want to ensure that the workloads move to the new nodes from the old nodes.

Upgrade a node pool

By default, a cluster's nodes have auto-upgrade enabled. Node auto-upgrades ensure that your cluster's control plane and node version remain in sync and in compliance with the Kubernetes version skew policy, which ensures that control planes are compatible with nodes up to two minor versions older than the control plane. For example, Kubernetes 1.29 control planes are compatible with Kubernetes 1.27 nodes.

Best practice:

Avoid disabling node auto-upgrades so that your cluster benefits from the upgrades listed in the preceding paragraph.

With GKE node pool upgrades, you can choose between two configurable upgrade strategies, namely surge upgrades and blue-green upgrades.

Choose a strategy and use the parameters to tune the strategy to best fit your cluster environment's needs.

How node upgrades work

While a node is being upgraded, GKE stops scheduling new Pods onto it, and attempts to schedule its running Pods onto other nodes. This is similar to other events that re-create the node, such as enabling or disabling a feature on the node pool.

During automatic or manual node upgrades, PodDisruptionBudgets (PDBs) and Pod termination grace period are respected for a maximum of 1 hour. If Pods running on the node can't be scheduled onto new nodes after one hour, GKE initiates the upgrade anyway. This behavior applies even if you configure your PDBs to always have all of your replicas available by setting the maxUnavailable field to 0 or 0% or by setting the minAvailable field to 100% or to the number of replicas. In all of these scenarios, GKE deletes the Pods after one hour so that the node deletion can happen.

Best practice:

If a workload requires more flexibility with graceful termination, use blue-green upgrades which provide settings for additional soak time to extend PDB checks beyond the one hour default.

To learn more about what to expect during node termination in general, see the topic about Pods.

If a workload requires more flexibility with graceful termination, we recommend using blue-green upgrades, which provide settings for additional soak time to extend PDB checks beyond the 1 hour default. For more information about what to expect during node termination in general, see the topic about Pods.

The upgrade is only complete when all nodes have been recreated and the cluster is in the desired state. When a newly-upgraded node registers with the control plane, GKE marks the node as schedulable.

New node instances run the desired Kubernetes version as well as:

Manually upgrade a node pool

You can manually upgrade a node pool version to match the version of the control plane or to a previous version that is still available and is compatible with the control plane. You can manually upgrade multiple node pools in parallel, whereas GKE automatically upgrades only one node pool at a time.

When you manually upgrade a node pool, GKE removes any labels you added to individual nodes using kubectl. To avoid this, apply labels to node pools instead.

Before you manually upgrade your node pool, consider the following conditions:

  • Upgrading a node pool may disrupt workloads running in that node pool. To avoid this, you can create a new node pool with the desired version and migrate the workload. After migration, you can delete the old node pool.
  • If you upgrade a node pool with an Ingress in an errored state, the instance group does not sync. To work around this issue, first check the status using the kubectl get ing command. If the instance group is not synced, you can work around the problem by re-applying the manifest used to create the ingress.

You can manually upgrade your node pools to a version compatible with the control plane, using the Google Cloud console or the Google Cloud CLI.

gcloud

The following variables are used in the commands in this section:

  • CLUSTER_NAME: the name of the cluster of the node pool to be upgraded.
  • NODE_POOL_NAME: the name of the node pool to be upgraded.
  • VERSION: the Kubernetes version to which the nodes are upgraded. For example, --cluster-version=1.7.2 or cluster-version=latest.

Upgrade a node pool:

gcloud container clusters upgrade CLUSTER_NAME \
  --node-pool=NODE_POOL_NAME

To specify a different version of GKE on nodes, use the optional --cluster-version flag:

gcloud container clusters upgrade CLUSTER_NAME \
  --node-pool=NODE_POOL_NAME \
  --cluster-version VERSION

For more information about specifying versions, see Versioning.

For more information, refer to the gcloud container clusters upgrade documentation.

Console

To upgrade a node pool using the Google Cloud console, perform the following steps:

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

    Go to Google Kubernetes Engine

  2. Next to the cluster you want to edit, click Actions, then click Edit.

  3. On the Cluster details page, click the Nodes tab.

  4. In the Node Pools section, click the name of the node pool that you want to upgrade.

  5. Click Edit.

  6. Click Change under Node version.

  7. Select the desired version from the Node version drop-down list, then click Change.

It may take several minutes for the node version to change.

Deploy a Pod to a specific node pool

You can explicitly deploy a Pod to a specific node pool by using a nodeSelector in your Pod manifest. nodeSelector schedules Pods onto nodes with a matching label.

All GKE node pools have labels with the following format: cloud.google.com/gke-nodepool: POOL_NAME. Add this label to the nodeSelector field in your Pod as shown in the following example:

apiVersion: v1
kind: Pod
metadata:
  name: nginx
  labels:
    env: test
spec:
  containers:
  - name: nginx
    image: nginx
    imagePullPolicy: IfNotPresent
  nodeSelector:
    cloud.google.com/gke-nodepool: POOL_NAME

For more information, see Assigning Pods to Nodes.

As an alternative to node selector, you can use node affinity. Use node affinity if you want a "soft" rule where the Pod attempts to meet the constraint, but is still scheduled even if the constraint can't be satisfied. For more information, see Node affinity. You can also specify resource requests for the containers.

Downgrade a node pool

You can downgrade a node pool, for example, to mitigate an unsuccessful node pool upgrade. Review the limitations before downgrading a node pool.

Best practice:

Use the blue-green node upgrade strategy if you need to optimize for risk mitigation for node pool upgrades impacting your workloads. With this strategy, you can roll backan in-progress upgrade to the original nodes if the upgrade is unsuccessful.

  1. Set a maintenance exclusion for the cluster to prevent the node pool from being automatically upgraded by GKE after being downgraded.
  2. To downgrade a node pool, specify an earlier version while following the instructions to Manually upgrade a node pool.

Delete a node pool

Deleting a node pool deletes the nodes and all running workloads, not respecting PodDisruptionBudget settings. To learn more about how this affects your workloads, including interactions with node selectors, see Deleting node pools.

gcloud

To delete a node pool, run the gcloud container node-pools delete command:

gcloud container node-pools delete POOL_NAME \
    --cluster CLUSTER_NAME

Console

To delete a node pool, perform the following steps:

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

    Go to Google Kubernetes Engine

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

  3. Click the Nodes tab.

  4. In the Node Pools section, click next to the node pool you want to delete.

  5. When prompted to confirm, click Delete.

Troubleshoot

For troubleshooting information, see Troubleshoot Standard node pools and Troubleshoot node registration.

What's next