Adding and managing node pools

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

Before you begin

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

Set up default gcloud settings using one of the following methods:

  • Using gcloud init, if you want to be walked through setting defaults.
  • Using gcloud config, to individually set your project ID, zone, and region.

Using gcloud init

If you receive the error One of [--zone, --region] must be supplied: Please specify location, complete this section.

  1. Run gcloud init and follow the directions:

    gcloud init

    If you are using SSH on a remote server, use the --console-only flag to prevent the command from launching a browser:

    gcloud init --console-only
  2. Follow the instructions to authorize gcloud to use your Google Cloud account.
  3. Create a new configuration or select an existing one.
  4. Choose a Google Cloud project.
  5. Choose a default Compute Engine zone.

Using gcloud config

  • Set your default project ID:
    gcloud config set project project-id
  • If you are working with zonal clusters, set your default compute zone:
    gcloud config set compute/zone compute-zone
  • If you are working with regional clusters, set your default compute region:
    gcloud config set compute/region compute-region
  • Update gcloud to the latest version:
    gcloud components update

Adding a node pool

gcloud

To create a node pool, run the following command:

gcloud container node-pools create pool-name --cluster cluster-name

For the full list of options, refer to the gcloud container node-pools create documentation.

A successful node-pools create request returns the node pool information:

Creating node pool example-pool...done.
Created [https://container.googleapis.com/v1/projects/kubernetes-engine-docs/zones/us-central1-f/clusters/example-cluster/nodePools/example-pool].
NAME          MACHINE_TYPE   DISK_SIZE_GB  NODE_VERSION
example-pool  e2-medium      100           1.2.4

The node pool is created. 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 ones 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 cluster, perform the following steps:

  1. Visit the Google Kubernetes Engine menu in Cloud Console.

    Visit the Google Kubernetes Engine menu

  2. Click the cluster's Edit button, which looks like a pencil.

  3. Click Add Node Pool.

  4. Configure your node pool as desired.

  5. Click Done to close the Add node pool overlay.

  6. Click Save to modify the cluster.

Viewing node pools in a cluster

gcloud

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

gcloud container node-pools list --cluster cluster-name

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

gcloud container node-pools describe pool-name \
    --cluster cluster-name

Console

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

  1. Visit the Google Kubernetes Engine menu in Cloud Console.

    Visit the Google Kubernetes Engine menu

  2. Click the name of the cluster you want to view.

  3. In the Node Pools section, click the disclosure icon beside the desired node pool. The menu expands to display details about the node pool.

  4. Click Done to exit the node pool details overview.

Resizing a node pool

gcloud

To resize a node pool, you use the gcloud container clusters resize command. You must specify the cluster's name, the name of the desired node pool, and the new number of nodes:

gcloud container clusters resize cluster-name --node-pool pool-name \
    --num-nodes num-nodes

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

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

Console

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

  1. Visit the Google Kubernetes Engine menu in Cloud Console.

    Visit the Google Kubernetes Engine menu

  2. Click the cluster's edit button, which looks like a pencil.

  3. In the Node Pools section, change the value of the Size field to the desired value. Repeat for each node pool as needed.

  4. Click Save.

Upgrading a node pool

gcloud

To update all nodes to the same version as the master, run the gcloud container clusters upgrade command:

gcloud container clusters upgrade cluster-name

To update a specific node pool, specify the --node-pool flag:

gcloud container clusters upgrade cluster-name --node-pool pool-name

Console

To upgrade a node pool, perform the following steps:

  1. Visit the Google Kubernetes Engine menu in Cloud Console.

    Visit the Google Kubernetes Engine menu

  2. Click the cluster's edit button, which looks like a pencil.

  3. In the Node Pools section, click the Change link beside the desired node pool's Node version field.

  4. Select the desired Kubernetes version.

  5. Read the warning, then click Change to confirm.

  6. Click Save to exit the cluster modification screen.

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: nodepool-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: nodepool-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.

Deleting a node pool

Deleting a node pool deletes the nodes and routes to them. Any Pods running on those nodes are evicted and rescheduled. If the Pods have specific node selectors, the Pods might remain in an unschedulable condition if no other node in the cluster satisfies the criteria.

gcloud

To delete a node pool, run the gcloud 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. Visit the Google Kubernetes Engine menu in Cloud Console.

    Visit the Google Kubernetes Engine menu

  2. Click the cluster's edit button, which looks like a pencil.

  3. In the Node Pools section, expand the node pool you want to delete.

  4. Click the delete icon, which looks like a garbage can.

  5. Click Save.

What's next