Update your AWS cluster parameters

This page describes how to update your GKE on AWS cluster's settings. You can use these instructions to update any updatable setting in your cluster, including the Kubernetes version. Because upgrading the version is one of the most common cluster update operations, a separate upgrade your cluster page covers how to upgrade a cluster version.

Reasons to update a cluster

You might update a cluster for any of the following reasons:

• To update your cluster's description.
• To update your cluster's annotations.
• To update your cluster's list of administrative users.
• To update your cluster's logging configuration.
• To rotate your encryption keys.
• To update your cluster control plane's security groups.

You can also update other fields in your clusters not listed here. For a complete list of fields you can update, see the gcloud container aws clusters update and the projects.locations.awsClusters.patch documentation.

Prerequisites

• To update any of your cluster's fields, you must have the gkemulticloud.googleapis.com/awsClusters.update Identity and Access Management permission.

• To update your cluster's security groups, your cluster's control plane role must have the ec2:ModifyNetworkInterfaceAttribute permission. For more information, see Create the control plane role.

• In addition, to update your cluster's tags, your cluster's API role must have the following AWS permissions:

  • autoscaling:CreateOrUpdateTags
  • autoscaling:DeleteTags
  • ec2:CreateTags
  • ec2:DescribeLaunchTemplates
  • ec2:DescribeSecurityGroupRules
  • ec2:DeleteTags
  • elasticloadbalancing:AddTags
  • elasticloadbalancing:RemoveTags

  Read Create AWS IAM roles to learn how to create and add permissions to your cluster's API role.

The update process

The process by which GKE on AWS updates a cluster differs depending on the type of update. For some changes, GKE on AWS can update a cluster without restarting or recreating any resources—for example, updating a cluster's description. GKE on AWS makes these changes immediately.

Other changes require restarting the control plane nodes—for example, updating the Kubernetes version. For such updates, GKE on AWS performs a "rolling update" consisting of the following steps:

1. Choose one control plane instance to update. GKE on AWS updates unhealthy instances, if any, before healthy ones.
2. Create a new launch template for the instance.
3. Update the Auto Scaling group's launch template.
4. Delete the instance. AWS recreates the instance and the instance boots with the new configuration.
5. Perform health checks on the new instance.
6. 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.
7. 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 cluster
• GOOGLE_CLOUD_LOCATION: the Google Cloud region that manages your cluster

Update your cluster

You can use either the Google Cloud console, the Google Cloud CLI, or the GKE Multi-Cloud API to update multiple cluster fields at once.

Choose an update method

You can update most fields through either the console, the gcloud CLI, or the GKE Multi-Cloud API. Some fields can only be updated through one mechanism or the other. If you want to use the console to update 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

1. In the Google Cloud console, go to the Google Kubernetes Engine clusters overview page.

   Go to GKE clusters

2. Select the Google Cloud project that the cluster is in.

3. In the cluster list, select the name of the cluster, and then select View details in the side panel.

4. On the Details tab, select Edit on the field that you want to change.

   For example, to grant cluster administrative privileges to other users select Edit next to Admin users and enter the email address of the user.

5. When you are finished making changes, select Done.

gcloud

When you update a cluster using the gcloud CLI, you must always include theCLUSTER_NAME and GOOGLE_CLOUD_LOCATION fields, which tell GKE on AWS what cluster to update. In the following command, only include the fields that you want to update; remove the other fields before running the command.

gcloud container aws clusters update CLUSTER_NAME \
    --location=GOOGLE_CLOUD_LOCATION \
    --cluster-version=CLUSTER_VERSION \
    --admin-users=USERNAME_LIST \
    --root-volume-iops=ROOT_VOLUME_IOPS \
    --root-volume-size=ROOT_VOLUME_SIZE \
    --root-volume-type=ROOT_VOLUME_TYPE \
    --security-group-ids=SECURITY_GROUP_IDS

Replace the following:

• CLUSTER_NAME: the name of your cluster
• GOOGLE_CLOUD_LOCATION (required): the supported Google Cloud region that manages your cluster—for example, us-west1
• CLUSTER_VERSION: the new supported cluster version
• USERNAME_LIST: a comma-separated list of usernames, for example, "[e-mail],[e-mail],[e-mail]". These are the email addresses of the users you're granting administrative privileges on this cluster to. The names in this setting will replace any previous list of admin-users on the cluster.
• ROOT_VOLUME_IOPS: the root volume's maximum I/O operations per second
• ROOT_VOLUME_SIZE: the root volume's size, in Gb
• ROOT_VOLUME_TYPE: the root volume's AWS EBS volume type
• SECURITY_GROUP_IDS: the AWS security group IDs to add to the cluster control plane instances
• SECURITY_GROUP_IDS: the AWS security group IDs to add to the cluster control plane instances

API

When you update a cluster using the GKE Multi-Cloud API, you must always include theCLUSTER_NAME and GOOGLE_CLOUD_LOCATION fields in the HTTP request. These fields tell GKE on AWS what cluster to update. You must also include the API endpoint in the request. You create a JSON file with the fields that you want to update. Only include the fields that you want to update in the JSON file and in the UPDATE_MASK.

The following example shows how to update your cluster through the API. For more information, including the list of fields that you can update, see the projects.locations.awsClusters.patch method documentation.

1. Create a JSON file named cluster_update.json with the fields that you want to update.

   {
       "controlPlane": {
          "version": "CLUSTER_VERSION",
       },
       "description": "CLUSTER_DESCRIPTION",
       "authorization": {
           "adminUsers": [
               {
               "username": USERNAME1,
               "username": USERNAME2,
               "username": USERNAME3
               }
           ]
       }
   }
   

   Replace the following:

   • CLUSTER_VERSION: the new supported cluster version. Note that you must upgrade through all minor versions when upgrading your cluster
   • CLUSTER_DESCRIPTION: the new cluster description
   • USERNAME1,USERNAME2,USERNAME3: the email addresses of the users you're granting administrative privileges on this cluster to. The names in these fields will replace any previous list of admin-users on the cluster.

2. 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_NAME?update_mask=UPDATE_MASK
   

Replace the following:

• ENDPOINT (required): Your Google Cloud service endpoint
• PROJECT_ID (required): Your Google Cloud project
• GOOGLE_CLOUD_LOCATION (required): the supported Google Cloud region that manages your cluster—for example, us-west1
• CLUSTER_NAME (required): Your cluster name
• UPDATE_MASK (required): a comma-separated list of one or more of the following flags, indicating which fields you want to update. In this example, specify the following.
  • controlPlane.version
  • description
  • authorization.admin_users

Update your cluster's security groups

To update your cluster's security groups, your cluster's control plane role must have the ec2:ModifyNetworkInterfaceAttribute permission. For more information, see Create the control plane role.

You can use the gcloud container aws clusters update command to add additional security groups to your cluster control plane.

gcloud container aws clusters update CLUSTER_NAME \
    --location=GOOGLE_CLOUD_LOCATION \
    --security-group-ids=SECURITY_GROUP_IDS

Replace the following:

• CLUSTER_NAME: your cluster's name
• GOOGLE_CLOUD_LOCATION: the supported Google Cloud region that manages your cluster—for example, us-west1
• SECURITY_GROUP_IDS: the AWS security group IDs to add to the cluster control plane instances

Remove cluster security groups

You can remove all the non-default security groups from your cluster with the Google Cloud CLI. To update a cluster, run:

gcloud container aws clusters update CLUSTER_NAME \
    --location=GOOGLE_CLOUD_LOCATION \
    --clear-security-group-ids

Replace the following:

• CLUSTER_NAME: your cluster's name
• GOOGLE_CLOUD_LOCATION: the supported Google Cloud region that manages your cluster—for example, us-west1

Update cluster volume information

You can update your cluster's control plane volumes with the Google Cloud CLI. To update volume KMS keys, see Key rotation.

To update volume size, type, or IOPS, run the following command:

gcloud container aws clusters update CLUSTER_NAME \
    --location=GOOGLE_CLOUD_LOCATION \
    --root-volume-iops=ROOT_VOLUME_IOPS
    --root-volume-size=ROOT_VOLUME_SIZE
    --root-volume-type=ROOT_VOLUME_TYPE

Replace the following:

• CLUSTER_NAME: your cluster's name
• GOOGLE_CLOUD_LOCATION: the supported Google Cloud region that manages your cluster—for example, us-west1
• ROOT_VOLUME_IOPS: the root volume's IO operations per second
• ROOT_VOLUME_SIZE: the root volume's size, in Gb
• ROOT_VOLUME_TYPE: the root volume's AWS EBS volume type.

Update Logging Config

You can update your cluster's Cloud Logging configuration settings with the Google Cloud CLI. To update the logging configuration, run the following command:

gcloud container aws clusters update CLUSTER_NAME \
    --location=GOOGLE_CLOUD_LOCATION \
    --logging=LOGGING_CONFIG \

Replace the following:

• CLUSTER_NAME: your cluster's name
• GOOGLE_CLOUD_LOCATION: the supported Google Cloud region that manages your cluster—for example, us-west1
• LOGGING_CONFIG: [SYSTEM] or [SYSTEM,WORKLOAD]

What's next

• To update volume KMS keys, see Key rotation
• For more information on updatable fields, see the gcloud container aws clusters update reference documentation.
• See the projects.locations.awsClusters.patch REST API documentation.