This page explains how to upgrade the Kubernetes version of your GKE on AWS clusters.
Prerequisites
Upgrading your cluster's Kubernetes version is a specific case of the more general cluster update operation. You can read about cluster update operations in general at the update your cluster page. To upgrade your cluster version:
- You must upgrade through every minor version between the current and target version. For example, to upgrade from 1.20 to 1.22, you must first upgrade from 1.20 to 1.21, and then upgrade from 1.21 to 1.22.
- You must have the
gkemulticloud.googleapis.com/awsClusters.update
Identity and Access Management permission.
How GKE on AWS performs updates
Because upgrading a cluster requires restarting the control plane nodes, GKE on AWS performs a "rolling update" with the following steps:
- Choose one control plane instance to update. GKE on AWS updates unhealthy instances, if any, before healthy ones.
- Create a new launch template for the instance.
- Update the Auto Scaling group's launch template.
- Delete the instance. AWS recreates the instance and the instance boots with the new configuration.
- Perform health checks on the new instance.
- If the health checks succeed, select another instance and perform the same
steps on it. Repeat this cycle until all instances
are restarted or recreated. If the health check fails, GKE on AWS
places the cluster into a
DEGRADED
state and stops the update. For more information, see the following section. - Delete the original launch template.
When an update fails
After an update, GKE on AWS performs a health check on the cluster.
If the health check fails, the cluster is marked as DEGRADED
. You can display
the status of your cluster with the following Google Cloud CLI command:
gcloud container aws clusters describe CLUSTER_NAME \
--location=GOOGLE_CLOUD_LOCATION
Replace the following:
CLUSTER_NAME
: the name of your clusterGOOGLE_CLOUD_LOCATION
: the Google Cloud region that manages your cluster
Perform the upgrade
Check your cluster version
Before upgrading your cluster version, use the following command to check which versions are available in your region:
gcloud container aws get-server-config \
--location=GOOGLE_CLOUD_LOCATION
Replace GOOGLE_CLOUD_LOCATION
with the Google Cloud
location from which you manage your clusters.
Choose an upgrade method
You can upgrade your cluster version through either the Google Cloud console, the Google Cloud CLI or the GKE Multi-Cloud API. If you want to use the console to upgrade a cluster, you must first choose and configure an authentication method for logging in to the cluster. For more information, see Connect and authenticate to your cluster.
Console
In the Google Cloud console, go to the Google Kubernetes Engine clusters overview page.
Select the Google Cloud project that the cluster is in.
In the cluster list, select the name of the cluster, and then select View details in the side panel.
On the Details tab, select
Upgrade.In the Upgrade the Kubernetes version for the cluster dialog box, select the version that you want to upgrade to and click Done. Note that you must upgrade through all minor versions when upgrading your cluster.
gcloud
To upgrade your cluster's Kubernetes version, run the following command:
gcloud container aws clusters update CLUSTER_NAME \
--location=GOOGLE_CLOUD_LOCATION \
--cluster-version=CLUSTER_VERSION
Replace the following:
CLUSTER_NAME
: your cluster's nameGOOGLE_CLOUD_LOCATION
: the supported Google Cloud region that manages your cluster—for example,us-west1
CLUSTER_VERSION
: the new supported cluster version
API
To update your cluster through the API, use a PATCH
operation on the
GKE Multi-Cloud API.
Create a JSON file named
cluster_update.json
with the following contents:{ "controlPlane": { "version": "CLUSTER_VERSION", }, }
Replace the following:
CLUSTER_VERSION
: the new supported cluster version. Note that you must upgrade through all minor versions when upgrading your cluster
Update these settings through the GKE Multi-Cloud API with following command.
curl -d @cluster_update.json -X PATCH \ ENDPOINT/projects/PROJECT_ID/locations/GOOGLE_CLOUD_LOCATION/awsClusters/CLUSTER_ID?update_mask=controlPlane.Version
Replace the following:
ENDPOINT
: Your Google Cloud service endpointPROJECT_ID
: Your Google Cloud projectGOOGLE_CLOUD_LOCATION
: the supported Google Cloud region that manages your cluster—for example,us-west1
CLUSTER_ID
: Your cluster ID
For more information, see the
projects.locations.awsClusters.patch
method documentation.
Upgrade your node pools
After you upgrade your cluster version, upgrade your node pools to complete the process. To learn how, see Update a node pool.
What's next
Learn how to perform other cluster updates.
For more information on updatable fields, see the
gcloud container aws clusters update
reference documentation.See the
projects.locations.awsClusters.patch
REST API documentation.