GKE - Google Kubernetes Engine

GKE Deployment and Administration

Demo Manually upgrade a GKE cluster or a node pool

In this guide, you’ll learn how to upgrade your GKE control plane (master) and node pools using the gcloud CLI. Manual upgrades give you granular control over version selection and scheduling.

Table of Contents

  1. Prerequisites
  2. 1. Set Up Cloud Shell Environment
  3. 2. List Available GKE Versions
  4. 3. Inspect Your Cluster’s Current Version
  5. 4. Upgrade the Control Plane (Master)
  6. 5. Upgrade the Node Pool
  7. 6. Verify the Final Versions
  8. Links and References

Prerequisites

  • You have the Google Cloud SDK installed or are using Cloud Shell.
  • Your IAM account has the Kubernetes Engine Admin role or equivalent permissions.

Note

Ensure you’re authenticated:

gcloud auth login
gcloud auth application-default login

1. Set Up Cloud Shell Environment

Configure your active project and default compute zone:

gcloud config set project YOUR_PROJECT_ID
gcloud config set compute/zone us-west1-a

Replace YOUR_PROJECT_ID with your Google Cloud project ID.


2. List Available GKE Versions

Retrieve the supported control plane and node versions for your zone:

gcloud container get-server-config

Sample output:

defaultClusterVersion: 1.27.3-gke.100
validMasterVersions:
- 1.27.3-gke.900
- 1.27.3-gke.100
- 1.27.2-gke.2100
validNodeVersions:
- 1.27.4-gke.900
- 1.27.3-gke.1700
- 1.27.2-gke.2100
validImageTypes:
- COS_CONTAINERD
- UBUNTU_CONTAINERD
- WINDOWS_LTSC_CONTAINERD
FieldDescription
defaultClusterVersionVersion applied when no override is provided
validMasterVersionsAvailable versions for the control plane (master)
validNodeVersionsAvailable versions for the node pools
validImageTypesContainer-optimized OS images supported for node pools

3. Inspect Your Cluster’s Current Version

Describe your cluster to view its current master and node versions:

gcloud container clusters describe gke-deep-dive

Look for these key fields:

currentMasterVersion: 1.27.3-gke.100
currentNodeVersion:   1.27.3-gke.100
nodePools:
- name: default-pool
  config:
    imageType: COS_CONTAINERD
    machineType: e2-medium
  management:
    autoUpgrade: true
    autoRepair: true
FieldCurrent ValueDescription
currentMasterVersion1.27.3-gke.100Control plane version
currentNodeVersion1.27.3-gke.100Node pool version
nodePools[].managementautoUpgrade: trueAutomatic upgrades enabled for nodes

4. Upgrade the Control Plane (Master)

Upgrade the control plane to a target version (for example, 1.27.3-gke.1700):

gcloud container clusters upgrade gke-deep-dive \
  --master \
  --cluster-version 1.27.3-gke.1700

When prompted:

Do you want to continue (Y/n)? Y

Warning

Control plane upgrades can cause brief API server interruptions. Plan a maintenance window if running production workloads.

This operation updates only the control plane.


5. Upgrade the Node Pool

After the master upgrade finishes, proceed with the node pool. By default, omitting --cluster-version upgrades nodes to match the control plane version.

To specify a different version (e.g., 1.27.4-gke.900):

gcloud container clusters upgrade gke-deep-dive \
  --node-pool default-pool \
  --cluster-version 1.27.4-gke.900

Confirm the prompt:

Do you want to continue (Y/n)? Y

Nodes are cordoned, drained, and replaced one at a time based on your pool’s update strategy.


6. Verify the Final Versions

Re-run the describe command to confirm both versions:

gcloud container clusters describe gke-deep-dive

Expected output:

currentMasterVersion: 1.27.3-gke.1700
currentNodeVersion:   1.27.4-gke.900

Your cluster is now running the specified master and node pool versions.


Watch Video

Watch video content

Previous
Upgrading your GKE cluster and node pools