Upgrade an admin or 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 admin or user cluster that is managed by the Anthos On-Prem API. For upgrade requirements, best practices, and additional information about the upgrade process, review Upgrade best practices and Lifecycle and stages of cluster upgrades before proceeding.

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 user clusters using standard Google Cloud applications. The Anthos On-Prem API runs in Google Cloud's infrastructure. The Google Cloud console and the gcloud 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 bmctl, you can configure the cluster to be managed by the Anthos On-Prem API, which lets you use the standard clients.

Before you begin

Install command line tools

If you want to use the gcloud CLI to upgrade the cluster, or if you want to use the Connect gateway to run kubectl commands on your local computer (as opposed to the admin workstation), ensure that you have the following command-line tools installed:

The latest version of the gcloud CLI.
kubectl for running commands against Kubernetes clusters. If you need to install kubectl, follow these instructions.

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 user 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.

Version requirements

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.

An admin cluster can manage user clusters that are on the same or previous minor version. Managed user clusters can't be more than one minor version lower than the admin cluster.

Note the following limitations:

Only 1.13.1 or higher user clusters can be upgraded using the console or the gcloud CLI. If your user cluster is at 1.13.0 or lower, upgrade the cluster using bmctl.
You must upgrade an admin cluster before upgrading any associated user clusters. However, before upgrading the admin cluster to 1.14.3, make sure its associated user clusters are at version 1.13.1 or above.

Upgrade an admin cluster

Console

In the console, go to the Anthos clusters page.

Go to the Anthos clusters page
Select the Cloud project, and then select the cluster that you want to upgrade.
In the Details panel, click More details.
In the Cluster basics section, click Upgrade.
In the Choose target version list, select the version that you want to upgrade to. We recommend that you upgrade to the latest patch version.
Click Upgrade.

Before the cluster is upgraded, preflight checks run to validate cluster status and node health. If the preflight checks pass, the admin cluster is upgraded. It takes 30 minutes or more for the upgrade to complete, depending on the size of your cluster.

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

gcloud CLI

Run the following command to log in with your Google account:
```
gcloud auth login
```
Update the Google Cloud CLI components:
```
gcloud components update
```
Get a list of available versions to upgrade to:
```
gcloud alpha container bare-metal admin-clusters query-version-config \
--cluster=ADMIN_CLUSTER_NAME \
--project=FLEET_HOST_PROJECT_ID \
--location=REGION
```
Replace the following:
- ADMIN_CLUSTER_NAME: The name of the admin cluster.
- FLEET_HOST_PROJECT_ID: The ID of the fleet project in which that admin cluster is a member. This is the project ID that you specified in the gkeConnect.projectID field in the cluster configuration file when you created the cluster.
- REGION: The Google Cloud region in which the Anthos On-Prem API runs and stores its metadata. This is the region that you selected when you enrolled the cluster for management with the Anthos On-Prem API.
Upgrade a cluster:
```
gcloud alpha container bare-metal admin-clusters update ADMIN_CLUSTER_NAME \
  --project=FLEET_HOST_PROJECT_ID \
  --location=REGION \
  --version=VERSION
```
Replace the following:
- ADMIN_CLUSTER_NAME: The name of the admin cluster to upgrade.
- FLEET_HOST_PROJECT_ID: The ID of the fleet project in which that admin cluster is a member. This is the project ID that you specified in the gkeConnect.projectID field in the cluster configuration file when you created the cluster.
- REGION: The Google Cloud region in which the Anthos On-Prem API runs and stores its metadata. This is the region that you selected when you enrolled the cluster for management with the Anthos On-Prem API.
- VERSION: The Anthos clusters on bare metal version that you want to upgrade to. r>' }}`: The Anthos clusters on bare metal version that you want to upgrade to. Specify a version from the output of the previous command. We recommend that you upgrade to the latest patch version.
It takes 30 minutes or more for the upgrade to complete, depending on the size of your cluster.

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

gcloud alpha container bare-metal admin-clusters describe ADMIN_CLUSTER_NAME \
  --project=FLEET_HOST_PROJECT_ID \
  --location=REGION

For addition information on the fields and flags, see gcloud alpha container bare-metal admin-clusters reference.

Upgrade a user cluster

Console

In the console, go to the Anthos clusters page.

Go to the Anthos clusters page
Select the Cloud project, and then select the cluster that you want to upgrade.
In the Details panel, click More details.
In the Cluster basics section, click Upgrade.
In the Choose target version list, select the version that you want to upgrade to. The curated list contains only the latest patch releases.
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 30 minutes or more for the upgrade to complete, depending on the size of your cluster.

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

gcloud CLI

Run the following command to log in with your Google account:
```
gcloud auth login
```
Update the Google Cloud CLI components:
```
gcloud components update
```
Get a list of available versions to upgrade to:
```
gcloud alpha container bare-metal 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 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 bmctl, 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 bmctl, this is the region that you specified when you enrolled the cluster for management with the Anthos On-Prem API.
Upgrade a cluster:
```
gcloud alpha container bare-metal clusters update 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 bmctl, 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 bmctl, this is the region that you specified when you enrolled the cluster for management with the Anthos On-Prem API.
- VERSION: The Anthos clusters on bare metal 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 30 minutes or more for the upgrade to complete, depending on the size of your cluster.

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

gcloud alpha container bare-metal clusters describe USER_CLUSTER_NAME \
  --project=FLEET_HOST_PROJECT_ID \
  --location=REGION

For addition information on the fields and flags, see gcloud alpha container bare-metal clusters reference.