Upgrade a user cluster using Anthos On-Prem API clients

This page explains how to use the Google Cloud console or the Google Cloud CLI to upgrade an Google Distributed Cloud user cluster that is managed by the Anthos On-Prem API. Before upgrading a user cluster, we recommend that you review Upgrade best practices.

What is the Anthos On-Prem API?

The Anthos On-Prem API is a Google Cloud-hosted API that lets you manage the lifecycle of your on-premises clusters using Terraform and standard Google Cloud tools. The Anthos On-Prem API runs in Google Cloud's infrastructure. Terraform, the Google Cloud console, and the Google Cloud CLI are clients of the API, and they use the API to create, update, upgrade, and delete clusters in your data center. If you created the cluster using a standard client, the cluster is enrolled in the Anthos On-Prem API, which means you can use the standard clients to manage the lifecycle of the cluster (with some exceptions). If you created the cluster using gkectl, you can enroll the cluster in the Anthos On-Prem API, which lets you use the standard clients.

Before you begin

Set up the gcloud CLI

To use the gcloud CLI or Terraform to upgrade a cluster:

  1. Ensure that you have the latest version of the gcloud CLI. Update the gcloud CLI components, if needed:

    gcloud components update

IAM requirements

If you aren't a project owner, you must be granted the Identity and Access Management role roles/gkeonprem.admin on the Google Cloud project that the cluster was created in. For details on the permissions included in this role, see GKE on-prem roles in the IAM documentation.

To use the console to upgrade the cluster, at a minimum, you need the following:

  • roles/container.viewer. This role lets users view the GKE Clusters page and other container resources in the console. For details about the permissions included in this role, or to grant a role with read/write permissions, see Kubernetes Engine roles in the IAM documentation.

  • roles/gkehub.viewer. This role lets users view clusters in the console. For details about the permissions included in this role, or to grant a role with read/write permissions,see GKE Hub roles in the IAM documentation.

Upgrade options

If you have a 1.14 or higher admin cluster, you have the following options for upgrading user clusters managed by the Anthos On-Prem API:

  • Use the preview upgrade procedure described in the following section.
  • To upgrade using gkectl or the console without the preview upgrade procedure, see Upgrading Google Distributed Cloud.

You can upgrade directly to a version that is in the same minor release or the next minor release. For example, you can upgrade from 1.14.1 to 1.14.2, or from 1.13.1 to 1.14.1. Upgrading to a version that is more than one minor release higher than the installed version isn't allowed.

Upgrade a user cluster

On 1.14 and higher admin clusters, a controller is deployed on the admin cluster that lets you use the Anthos On-Prem API clients to upgrade user clusters. During the user cluster upgrade, the admin cluster is enrolled with the Anthos On-Prem API if it isn't already enrolled, which eliminates the need to run any commands on the admin workstation to upgrade user clusters. When you initiate a user cluster upgrade, the Anthos On-Prem API triggers the controller to prepare for the upgrade. The controller downloads and installs bundles. Next, the controller deploys the new version of the components that manage the user cluster.

To upgrade a user cluster:

Console

  1. In the console, go to the GKE Enterprise clusters page.

    Go to the GKE Enterprise clusters page

  2. Select the Google Cloud project, and then select the cluster that you want to upgrade.

  3. In the Details panel, click More details.

  4. In the Cluster basics section, click Upgrade.

  5. In the Choose target version list, select the version that you want to upgrade to. The curated list contains only the latest patch releases.

  6. Click Upgrade.

Before the cluster is upgraded, preflight checks run to validate cluster status and node health. If the preflight checks pass, the user cluster is upgraded. It takes about 30 minutes for the upgrade to complete.

To view the status of the upgrade, click Show Details on the Cluster Details tab.

gcloud CLI

  1. Run the following command to log in with your Google account:

    gcloud auth login

  2. Update the Google Cloud CLI components:

    gcloud components update

  3. Get a list of available versions to upgrade to:

    gcloud container vmware clusters query-version-config \
  --cluster=USER_CLUSTER_NAME \
  --project=FLEET_HOST_PROJECT_ID \
  --location=REGION

    Replace the following:

    • USER_CLUSTER_NAME:The name of the user cluster.

    • FLEET_HOST_PROJECT_ID: The ID of the fleet project in which that user cluster is a member. This is the project that you specified when the cluster was created. If you created the cluster using gkectl, this is the project ID in the gkeConnect.projectID field in the cluster configuration file.

    • REGION: The Google Cloud region in which the Anthos On-Prem API runs and stores its metadata. If you created the cluster using an Anthos On-Prem API client, this is the region that you specified when creating the cluster. If you created the cluster using gkectl, this is the region that you specified when you enrolled the cluster for management with the Anthos On-Prem API.

  4. Upgrade a cluster:

    gcloud container vmware clusters upgrade USER_CLUSTER_NAME \
  --project=FLEET_HOST_PROJECT_ID \
  --location=REGION \
  --version=VERSION

    Replace the following:

    • USER_CLUSTER_NAME: The name of the user cluster to upgrade.

    • FLEET_HOST_PROJECT_ID: The ID of the fleet project in which that user cluster is a member. This is the project that you specified when the cluster was created. If you created the cluster using gkectl, this is the project ID in the gkeConnect.projectID field in the cluster configuration file.

    • REGION: The Google Cloud region in which the Anthos On-Prem API runs and stores its metadata. If you created the cluster using an Anthos On-Prem API client, this is the region that you selected when creating the cluster. If you created the cluster using gkectl, this is the region that you specified when you enrolled the cluster for management with the Anthos On-Prem API.

    • VERSION: The Google Distributed Cloud version that you want to upgrade to. Specify a version from the output of the previous command. We recommend that you upgrade to the most recent patch version.

    It takes about 30 minutes for the upgrade to complete.

  5. While the cluster is upgrading, run the following command in another terminal window to check the status of the cluster:

    gcloud container vmware clusters describe USER_CLUSTER_NAME \
  --project=FLEET_HOST_PROJECT_ID \
  --location=REGION

For addition information on the fields and flags, see gcloud container vmware clusters upgrade.