Upgrading GKE on AWS

To upgrade your GKE on AWS environment, first upgrade your management service and then upgrade your user clusters.

Management service

In the following sections, you upgrade your management service.

Before you begin

To connect to your GKE on AWS resources, perform the following steps. Select if you have an existing AWS VPC (or direct connection to your VPC) or created a dedicated VPC when creating your management service.

Existing VPC

If you have a direct or VPN connection to an existing VPC, omit the line env HTTP_PROXY=http://localhost:8118 from commands in this topic.

Dedicated VPC

When you create a management service in a dedicated VPC, GKE on AWS includes a bastion host in a public subnet.

Important: If you restart your terminal session or the SSH connection is lost, you need to re-launch the bastion-tunnel.sh script.

To connect to your management service, perform the following steps:

1. Change to the directory with your GKE on AWS configuration. You created this directory when Installing the management service.

   cd anthos-aws

2. To open the tunnel, run the bastion-tunnel.sh script. The tunnel forwards to localhost:8118.

   To open a tunnel to the bastion host, run the following command:

   ./bastion-tunnel.sh -N
   

   Messages from the SSH tunnel appear in this window. When you are ready to close the connection, stop the process by using Control+C or closing the window.

3. Open a new terminal and change into your anthos-aws directory.

   cd anthos-aws

4. Check that you're able to connect to the cluster with kubectl.

   env HTTPS_PROXY=http://localhost:8118 \
   kubectl cluster-info
   

   The output includes the URL for the management service API server.

Upgrade your management service

To upgrade your management service, you download a new version of anthos-gke, edit your anthos-gke.yaml, and then apply the changes.

Download a new version of anthos-gke

The latest version of the anthos-gke tool is aws-1.14.1-gke.0. To download a new version of anthos-gke, perform the following steps:

The anthos-gke command-line tool only supports Linux and macOS.

1. Download the binary from Cloud Storage.

   Linux

   gcloud storage cp gs://gke-multi-cloud-release/aws/aws-1.14.1-gke.0/bin/linux/amd64/anthos-gke .
   

   macOS

   gcloud storage cp gs://gke-multi-cloud-release/aws/aws-1.14.1-gke.0/bin/darwin/amd64/anthos-gke .
   

2. Update the permissions of anthos-gke and copy it to /usr/local/bin.

   chmod 755 anthos-gke
   sudo mv anthos-gke /usr/local/bin
   

3. Confirm that the version is aws-1.14.1-gke.0

   anthos-gke version
   

Upgrade your management service

To upgrade your cluster, perform the following steps:

1. Change to the directory with your GKE on AWS configuration. You created this directory when Installing the management service.

   cd anthos-aws

2. Open your anthos-gke.yaml in a text editor. Change the value of spec.version to aws-1.14.1-gke.0.

   apiVersion: multicloud.cluster.gke.io/v1
   kind: AWSManagementService
   metadata:
    name: management
   spec:
    version: aws-1.14.1-gke.0
    region: aws-region
    ...
   

3. Run anthos-gke aws management init to validate the AWSManagementService object and update the anthos-gke.status.yaml file.

   anthos-gke aws management init
   

4. Run anthos-gke aws management apply to update the management service on AWS.

   anthos-gke aws management apply
   

   The anthos-gke command begins to upgrade your management service. The upgrade might take up to ten minutes to complete.

   Note: Your management service experiences downtime during an upgrade. You can't make any changes to your AWSCluster resources at this time. Your user clusters continue to run their workloads while the upgrade completes.

Note: If you have a bastion host in your GKE on AWS environment, it might restart during the upgrade. Restart your tunnel when the process is complete.

User clusters

In the following sections, you upgrade your user clusters.

Before you begin

Before you can complete these steps, you must have a management service and at least one user cluster.

Supported Kubernetes versions

GKE on AWS aws-1.14.1-gke.0 supports the following Kubernetes versions:

• 1.23.15-gke.2000
• 1.24.9-gke.2100
• 1.25.5-gke.2100

For information on prior supported versions, see Release notes.

Note: Kubernetes 1.19, 1.20 and 1.21 are no longer supported by GKE on AWS.

Component upgrades

This section describes upgrading your AWSClusters and AWSNodePools.

AWSCluster

You can update an AWSCluster to a new version of GKE on AWS without updating your AWSNodePools.

AWSNodePools

You cannot update an AWSNodePool to a version newer than your AWSCluster. To update your AWSNodePools, you must first update your AWSCluster.

Your AWSNodePools version must be no less than two minor versions behind your AWSCluster version.

Upgrade an existing AWSCluster and AWSNodePool

To upgrade your cluster, you update the version field of AWSCluster and AWSNodePool objects on your management service.

AWSCluster

To upgrade an AWSCluster, perform the following steps:

1. From your anthos-aws directory, use anthos-gke to switch context to your management service.

   cd anthos-aws
   anthos-gke aws management get-credentials

   Note: anthos-gke uses the credentials you specified when you ran aws configure.

2. Open the YAML file that created your AWSCluster in a text editor. If you do not have your initial YAML file, you can use kubectl edit.

   Edit YAML

   If you followed the instructions in Creating a user cluster, your YAML file is named cluster-0.yaml. Open this file in a text editor.

   kubectl edit

   To use kubectl edit to edit your AWSCluster, run the following command:

   env HTTPS_PROXY=http://localhost:8118 \
     kubectl edit awscluster cluster-name
   

   Replace cluster-name with your AWSCluster. For example, to edit the default cluster, cluster-0, run the following command:

   env HTTPS_PROXY=http://localhost:8118 \
     kubectl edit awscluster cluster-0
   

3. Update the spec.controlPlane.version field to a new version of GKE on AWS. The most recent version is 1.25.5-gke.2100.

   apiVersion: multicloud.cluster.gke.io/v1
   kind: AWSCluster
   metadata:
     name: cluster-0
   spec:
     region: us-east-1
     controlPlane:
       version: gke_version
       instanceType: t3.medium
     ...
   

   Replace gke-version with your desired Kubernetes version. The most recent supported Kubernetes version is 1.25.5-gke.2100.

   Note: Downgrading a cluster to an earlier version is not supported.

4. Save the file. If you are using kubectl edit, kubectl applies the changes automatically. If you are editing the YAML file, apply it to your management service with the following command:

   env HTTPS_PROXY=http://localhost:8118 \
   kubectl apply -f cluster-0.yaml
   

   The management service then updates your AWSCluster.

AWSNodePool

To upgrade an AWSNodePool, perform the following steps:

1. From your anthos-aws directory, use anthos-gke to switch context to your management service.

   cd anthos-aws
   anthos-gke aws management get-credentials

   Note: anthos-gke uses the credentials you specified when you ran aws configure.

2. Open the YAML file that created your AWSNodePool in a text editor. If you followed the instructions in Creating a user cluster, this file is named cluster-0.yaml.

3. Update the value of spec.version in your AWSNodePool resources.

   apiVersion: multicloud.cluster.gke.io/v1
   kind: AWSNodePool
   metadata:
     name: cluster-0-pool-0
   spec:
     clusterName: cluster-0
     region: us-east-1
     version: gke-version
     ...
   

   Replace gke-version with your desired Kubernetes version. The most recent supported Kubernetes version is 1.25.5-gke.2100.

   Note: Downgrading an AWSNodePool to an earlier version is not supported.

4. Apply the new configuration to your management service with kubectl.

   env HTTPS_PROXY=http://localhost:8118 \
     kubectl apply -f cluster-0.yaml
   

   The management service then updates your AWSNodePool one node at a time. Before a node is shut down, Pods running on that node receive a SIGTERM. If a Pod does not shut down after a grace period, it receives a SIGKILL.

   Note: During an upgrade, your workloads are restarted on new nodes. You might experience downtime during an upgrade while workloads restart on a new node.

View Status

To get the status of an upgrade, run kubectl get AWSClusters on your management service.

env HTTPS_PROXY=http://localhost:8118 \
    kubectl get AWSClusters

The output includes each cluster's name, state, age, version, and endpoint. For example, the following output includes one AWSCluster named cluster-0.

NAME        STATE          AGE     VERSION         ENDPOINT
cluster-0   Upgrading   2m41s      1.25.5-gke.2100   gke-xyz.elb.us-east-1.amazonaws.com

Your user cluster upgrade is complete when the STATE of your clusters is Provisioned.