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:
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.
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
In the console, go to the GKE Enterprise clusters page.
Select the Google 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
editUpgrade.
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 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
Run the following command to log in with your Google account:
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.
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.
While the cluster is upgrading, run the following command in another
terminal window to check the status of the cluster:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[[["\u003cp\u003eThis guide outlines the process of upgrading Google Distributed Cloud user clusters managed by the Anthos On-Prem API, using either the Google Cloud console or the gcloud CLI.\u003c/p\u003e\n"],["\u003cp\u003eThe Anthos On-Prem API enables lifecycle management of on-premises clusters through standard Google Cloud tools, including Terraform, the Google Cloud console, and the Google Cloud CLI.\u003c/p\u003e\n"],["\u003cp\u003eUpgrades can only be done to a version within the same minor release or to the next minor release, for example, upgrading from 1.14.1 to 1.14.2 or 1.13.1 to 1.14.1.\u003c/p\u003e\n"],["\u003cp\u003eBefore initiating an upgrade, ensure the gcloud CLI is up-to-date and that the necessary IAM roles, such as \u003ccode\u003eroles/gkeonprem.admin\u003c/code\u003e, \u003ccode\u003eroles/container.viewer\u003c/code\u003e, and \u003ccode\u003eroles/gkehub.viewer\u003c/code\u003e, are granted to the user.\u003c/p\u003e\n"],["\u003cp\u003eThe upgrade process involves preflight checks to validate cluster status and node health, and once initiated, it typically takes about 30 minutes to complete.\u003c/p\u003e\n"]]],[],null,["# Upgrade a user cluster using Anthos On-Prem API clients\n\n\u003cbr /\u003e\n\nThis page explains how to use the Google Cloud console or the Google Cloud CLI to\nupgrade an Google Distributed Cloud user cluster that is managed by the Anthos On-Prem API.\nBefore upgrading a user cluster, we recommend that you review\n[Upgrade best practices](/anthos/clusters/docs/on-prem/1.14/how-to/upgrade-best-practices).\n\nWhat is the Anthos On-Prem API?\n-------------------------------\n\nThe Anthos On-Prem API is a Google Cloud-hosted API that lets you manage the\nlifecycle of your on-premises clusters using Terraform and standard\nGoogle Cloud tools. The Anthos On-Prem API runs in Google Cloud's\ninfrastructure. Terraform, the Google Cloud console, and the Google Cloud CLI are\nclients of the API, and they use the API to create, update, upgrade, and\ndelete clusters in your data center. If you created the cluster using\na standard client, the cluster is *enrolled* in the Anthos On-Prem API, which\nmeans you can use the standard clients to manage the lifecycle of the cluster\n(with some exceptions).\n\nIf you created the cluster using `gkectl`, you can\n[enroll the cluster in the\nAnthos On-Prem API](/anthos/clusters/docs/on-prem/1.14/how-to/enroll-cluster), which lets you use the standard clients.\n\n\nBefore you begin\n----------------\n\n### Set up the gcloud CLI\n\nTo use the gcloud CLI or Terraform to upgrade a cluster:\n\n1. Ensure that you have\n [the latest version of the gcloud CLI](/sdk/docs/install). Update\n the gcloud CLI components, if needed:\n\n gcloud components update\n\n### IAM requirements\n\nIf you aren't a project owner, you must be granted the Identity and Access Management\nrole `roles/gkeonprem.admin` on the Google Cloud project that the cluster\nwas created in. For details on the permissions included in this role, see\n[GKE on-prem roles](/iam/docs/understanding-roles#gke-on-prem-roles)\nin the IAM documentation.\n\nTo use the console to upgrade the cluster, at a minimum, you need\nthe following:\n\n- `roles/container.viewer`. This role lets users view the GKE\n Clusters page and other container resources in the console. For\n details about the permissions included in this role, or to grant a role with\n read/write permissions, see\n [Kubernetes Engine roles](/iam/docs/understanding-roles#kubernetes-engine-roles)\n in the IAM documentation.\n\n- `roles/gkehub.viewer`. This role lets users view clusters in the\n console. For details about the\n permissions included in this role, or to grant a role with read/write\n permissions,see\n [GKE Hub roles](/iam/docs/understanding-roles#gke-hub-roles) in the\n IAM documentation.\n\nUpgrade options\n---------------\n\nIf you have a 1.14 or higher admin cluster, you have the following options for\nupgrading user clusters managed by the Anthos On-Prem API:\n\n- Use the preview upgrade procedure described in the following section.\n- To upgrade using `gkectl` or the console without the preview upgrade procedure, see [Upgrading Google Distributed Cloud](/anthos/clusters/docs/on-prem/1.14/how-to/upgrading).\n\nYou can upgrade directly to a version that is in the same minor release or\nthe next minor release. For example, you can upgrade from 1.14.1\nto 1.14.2, or from 1.13.1 to 1.14.1.\nUpgrading to a version that is more than one minor release higher than the\ninstalled version isn't allowed.\n| **Note:** If you have a 1.13 admin cluster, use the 1.13 version of [Upgrade a user cluster using Anthos On-Prem API clients](/anthos/clusters/docs/on-prem/1.14/how-to/upgrade-on-prem-api#upgrade_options).\n\nUpgrade a user cluster\n----------------------\n\nOn 1.14 and higher admin clusters, a controller is deployed on the admin cluster\nthat lets you use the Anthos On-Prem API clients to upgrade user clusters. During\nthe user cluster upgrade, the admin cluster is\n[enrolled with the Anthos On-Prem API](/anthos/clusters/docs/on-prem/1.14/how-to/enroll-cluster)\nif it isn't already enrolled, which eliminates the need to run any commands on\nthe admin workstation to upgrade user clusters. When you initiate a user\ncluster upgrade, the Anthos On-Prem API triggers the controller to prepare for\nthe upgrade. The controller downloads and installs bundles. Next, the\ncontroller deploys the new version of the components that manage the user\ncluster.\n\nTo upgrade a user cluster: \n\n### Console\n\n1. In the console, go to the GKE Enterprise clusters page.\n\n [Go to the GKE Enterprise clusters page](https://console.cloud.google.com/anthos/clusters)\n2. Select the Google Cloud project, and then select the cluster that you\n want to upgrade.\n\n3. In the **Details** panel, click **More details**.\n\n4. In the **Cluster basics** section, click\n edit **Upgrade**.\n\n5. In the **Choose target version** list, select the version that you want to\n upgrade to. The curated list contains only the latest patch releases.\n\n6. Click **Upgrade**.\n\nBefore the cluster is upgraded, preflight checks run to validate cluster\nstatus and node health. If the preflight checks pass, the user cluster is\nupgraded. It takes about 30 minutes for the upgrade to complete.\n\nTo view the status of the upgrade, click **Show Details** on the **Cluster\nDetails** tab.\n\n### gcloud CLI\n\n1. Run the following command to log in with your Google account:\n\n gcloud auth login\n\n2. Update the Google Cloud CLI components:\n\n gcloud components update\n\n3. Get a list of available versions to upgrade to:\n\n ```\n gcloud container vmware clusters query-version-config \\\n --cluster=USER_CLUSTER_NAME \\\n --project=FLEET_HOST_PROJECT_ID \\\n --location=REGION\n ```\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eUSER_CLUSTER_NAME\u003c/var\u003e:The name of the user cluster.\n\n - \u003cvar translate=\"no\"\u003eFLEET_HOST_PROJECT_ID\u003c/var\u003e: The ID of the fleet project\n in which that user cluster is a member. This is the project that you\n specified when the cluster was created. If you created the cluster\n using `gkectl`, this is the project ID in the `gkeConnect.projectID`\n field in the cluster configuration file.\n\n - \u003cvar translate=\"no\"\u003eREGION\u003c/var\u003e: The Google Cloud region in which the\n Anthos On-Prem API runs and stores its metadata. If you created the cluster\n using an Anthos On-Prem API client, this is the region that you specified\n when creating the cluster. If you created the cluster using `gkectl`,\n this is the region that you specified when you enrolled the cluster for\n management with the Anthos On-Prem API.\n\n4. Upgrade a cluster:\n\n ```\n gcloud container vmware clusters upgrade USER_CLUSTER_NAME \\\n --project=FLEET_HOST_PROJECT_ID \\\n --location=REGION \\\n --version=VERSION\n ```\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eUSER_CLUSTER_NAME\u003c/var\u003e: The name of the user cluster to\n upgrade.\n\n - \u003cvar translate=\"no\"\u003eFLEET_HOST_PROJECT_ID\u003c/var\u003e: The ID of the fleet project\n in which that user cluster is a member. This is the project that you\n specified when the cluster was created. If you created the cluster\n using `gkectl`, this is the project ID in the `gkeConnect.projectID`\n field in the cluster configuration file.\n\n - \u003cvar translate=\"no\"\u003eREGION\u003c/var\u003e: The Google Cloud region in which the\n Anthos On-Prem API runs and stores its metadata. If you created the cluster\n using an Anthos On-Prem API client, this is the region that you selected\n when creating the cluster. If you created the cluster using `gkectl`,\n this is the region that you specified when you enrolled the cluster for\n management with the Anthos On-Prem API.\n\n - \u003cvar translate=\"no\"\u003eVERSION\u003c/var\u003e: The Google Distributed Cloud version that you\n want to upgrade to. Specify a version from the output of the previous\n command. We recommend that you upgrade to the most recent patch version.\n\n It takes about 30 minutes for the upgrade to complete.\n5. While the cluster is upgrading, run the following command in another\n terminal window to check the status of the cluster:\n\n ```\n gcloud container vmware clusters describe USER_CLUSTER_NAME \\\n --project=FLEET_HOST_PROJECT_ID \\\n --location=REGION\n ```\n\nFor addition information on the fields and flags, see [gcloud container vmware clusters upgrade](/sdk/gcloud/reference/container/vmware/clusters/upgrade)."]]
