Version 1.13. This version is no longer supported. For information about how to upgrade to version 1.14, see Upgrading Anthos on bare metal in the 1.14 documentation. For more information about supported and unsupported versions, see the Version history page in the latest documentation.
The Anthos On-Prem API is a Google Cloud-hosted API that lets you manage the
lifecycle of your on-premises clusters by using standard tools: the
Google Cloud console, the Google Cloud CLI, or Terraform. When you create a
cluster using one of these tools, the API stores metadata about your cluster's
state in the Google Cloud region that you specified when creating the cluster.
This metadata lets you manage the lifecycle of the cluster using the
standard tools. If you want to use these tools to view cluster details or manage
the lifecycle of clusters that were created using bmctl, you must
enroll the clusters in the Anthos On-Prem API.
Terminology
Enrolling a cluster lets you manage the cluster lifecycle by using the
console, the gcloud CLI, or Terraform.
Enrolling a cluster is a separate process to registering a cluster to a fleet.
A fleet is a a logical grouping of Kubernetes clusters that you can manage
together. All Google Distributed Cloud clusters are registered to a fleet at cluster
creation time. When you create a cluster using bmctl, the cluster
is registered to the Google Cloud project that you specify in the
gkeConnect.projectID field in the cluster configuration file. This project
is referred to as the
fleet host project.
To learn more about fleets, including uses cases, best practices, and examples,
see the Fleet management documentation.
View registered clusters
All your fleet clusters are displayed on the
GKE Clusters
pages in the console. This both gives you an overview of your
entire fleet and, for Google Distributed Cloud, lets you see which clusters are
managed by the Anthos On-Prem API.
If Bare metal is displayed in the Type column, the
cluster is managed by the Anthos On-Prem API.
If External is displayed in the Type column, the cluster isn't
managed by the Anthos On-Prem API.
Requirements
Only user and admin clusters can be enrolled with the Anthos On-Prem API.
Enrolling hybrid and standalone clusters isn't supported.
Version 1.13 or higher.
If your organization has set up an allowlist that lets traffic from
Google APIs and other addresses pass through your
proxy server, add the following to the
allowlist:
gkeonprem.googleapis.com
gkeonprem.mtls.googleapis.com
These are the service names for the Anthos On-Prem API.
If you aren't a project owner, minimally, you must be granted the Identity and Access Management
role roles/gkeonprem.admin on the project. For details on the permissions
included in this role, see
GKE on-prem roles
in the IAM documentation.
Enroll a user cluster
To enroll a cluster for management by the Anthos On-Prem API:
Replace FLEET_HOST_PROJECT_ID with the project ID of
your fleet host project.
This is the project ID that was configured in the gkeconnect section of your
cluster configuration file.
Enroll the cluster with the Anthos On-Prem API:
User cluster
Be sure to scroll over if needed to fill in the
ADMIN_CLUSTER_NAME placeholder for the
--admin-cluster-membership flag.
USER_CLUSTER_NAME: The name of the user cluster
that you want to enroll.
FLEET_HOST_PROJECT_ID The project ID of
your fleet host project.
ADMIN_CLUSTER_NAME: The admin cluster
that manages the user cluster. The admin cluster name is the last
segment of the fully-specified cluster name that uniquely identifies
the cluster in Google Cloud.
LOCATION: The Google Cloud region in which
the Anthos On-Prem API runs. Specify us-west1 or another
supported region.
The region can't be changed after the cluster is enrolled. In addition
to setting the region where the Anthos On-Prem API runs, this is the
region in which the following is stored:
The user cluster metadata that the Anthos On-Prem API needs
to manage the cluster lifecycle
The Cloud Logging and Cloud Monitoring data of system components
ADMIN_CLUSTER_NAME: The name of the admin cluster
that you want to enroll.
FLEET_HOST_PROJECT_ID The project ID of
your fleet host project.
The ADMIN_CLUSTER_NAME and
FLEET_HOST_PROJECT_ID are used to form the
fully-specified cluster name for the --admin-cluster-membership
flag.
LOCATION: The Google Cloud region in which
the Anthos On-Prem API runs. Specify us-west1 or another
supported region.
The region can't be changed after the cluster is enrolled. In addition
to setting the region where the Anthos On-Prem API runs, this is the
region in which the following is stored:
The cluster metadata that the Anthos On-Prem API needs to manage the
cluster lifecycle
The Cloud Logging and Cloud Monitoring data of system components
The Admin Audit log created by Cloud Audit Logs
After the cluster is enrolled, you can use the following commands to
get information about your clusters:
gcloud container bare-metal admin-clusters list \
--project=FLEET_HOST_PROJECT_ID \
--location=LOCATION
Connect to the cluster
After the cluster is enrolled with the Anthos On-Prem API, you need to choose
and configure an authentication method so that you can
manage the cluster from the Google Cloud console.
The authentication method that you select also controls access to the cluster
from the command line. For more information, see the following:
[[["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\u003eThe Anthos On-Prem API is a Google Cloud-hosted API that enables management of on-premises clusters using standard tools like the Google Cloud console, the Google Cloud CLI, or Terraform.\u003c/p\u003e\n"],["\u003cp\u003eEnrolling a cluster in the Anthos On-Prem API allows lifecycle management via the console, gcloud CLI, or Terraform, which is distinct from registering a cluster to a fleet for unified management.\u003c/p\u003e\n"],["\u003cp\u003eOnly user and admin clusters (version 1.13 or higher) can be enrolled in the Anthos On-Prem API, with specific allowlist requirements for organizations using proxy servers.\u003c/p\u003e\n"],["\u003cp\u003eEnrolling a cluster involves enabling the Anthos On-Prem API in the fleet host project and using gcloud commands to enroll the user or admin cluster, specifying the fleet host project ID and the desired Google Cloud region.\u003c/p\u003e\n"],["\u003cp\u003eAfter enrollment, you can view clusters on the GKE Clusters page, utilize \u003ccode\u003egcloud\u003c/code\u003e commands to describe and list clusters, and configure an authentication method to manage the cluster from the Google Cloud console.\u003c/p\u003e\n"]]],[],null,["# Configure a cluster to be managed by the Anthos On-Prem API\n\n\u003cbr /\u003e\n\nThe Anthos On-Prem API is a Google Cloud-hosted API that lets you manage the\nlifecycle of your on-premises clusters by using standard tools: the\nGoogle Cloud console, the Google Cloud CLI, or Terraform. When you create a\ncluster using one of these tools, the API stores metadata about your cluster's\nstate in the Google Cloud region that you specified when creating the cluster.\nThis metadata lets you manage the lifecycle of the cluster using the\nstandard tools. If you want to use these tools to view cluster details or manage\nthe lifecycle of clusters that were created using `bmctl`, you must\n*enroll* the clusters in the Anthos On-Prem API.\n\n### Terminology\n\nEnrolling a cluster lets you manage the cluster lifecycle by using the\nconsole, the gcloud CLI, or Terraform.\n\nEnrolling a cluster is a separate process to registering a cluster to a *fleet* .\nA fleet is a a logical grouping of Kubernetes clusters that you can manage\ntogether. All Google Distributed Cloud clusters are registered to a fleet at cluster\ncreation time. When you create a cluster using bmctl, the cluster\nis registered to the Google Cloud project that you specify in the\n`gkeConnect.projectID` field in the cluster configuration file. This project\nis referred to as the\n[fleet host project](/anthos/fleet-management/docs/fleet-concepts#fleet-host-project).\nTo learn more about fleets, including uses cases, best practices, and examples,\nsee the [Fleet management](/anthos/fleet-management/docs) documentation.\n\n### View registered clusters\n\nAll your fleet clusters are displayed on the\n[GKE Clusters](https://console.cloud.google.com/kubernetes/list/overview)\npages in the console. This both gives you an overview of your\nentire fleet and, for Google Distributed Cloud, lets you see which clusters are\nmanaged by the Anthos On-Prem API.\n\nTo view your fleet clusters:\n\n1. In the console, go to the GKE clusters page. \n [Go to GKE clusters](https://console.cloud.google.com/kubernetes/list/overview)\n2. Select the Google Cloud project.\n - If **Bare metal** is displayed in the **Type** column, the cluster is managed by the Anthos On-Prem API.\n - If **External** is displayed in the **Type** column, the cluster isn't managed by the Anthos On-Prem API.\n\nRequirements\n------------\n\n- Only user and admin clusters can be enrolled with the Anthos On-Prem API. Enrolling hybrid and standalone clusters isn't supported.\n- Version 1.13 or higher.\n- If your organization has set up an allowlist that lets traffic from\n Google APIs and other addresses pass through your\n [proxy server](/anthos/clusters/docs/bare-metal/1.13/installing/proxy), add the following to the\n allowlist:\n\n - gkeonprem.googleapis.com\n - gkeonprem.mtls.googleapis.com\n\n These are the service names for the Anthos On-Prem API.\n- If you aren't a project owner, minimally, you must be granted the Identity and Access Management\n role `roles/gkeonprem.admin` on the project. For details on the permissions\n included in this role, see\n [GKE on-prem roles](/iam/docs/understanding-roles#gke-on-prem-roles)\n in the IAM documentation.\n\nEnroll a user cluster\n---------------------\n\nTo enroll a cluster for management by the Anthos On-Prem API:\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\n2. Enable the Anthos On-Prem API in your the fleet host project:\n\n gcloud services enable \\\n --project \u003cvar translate=\"no\"\u003eFLEET_HOST_PROJECT_ID\u003c/var\u003e \\\n gkeonprem.googleapis.com\n\n Replace \u003cvar translate=\"no\"\u003eFLEET_HOST_PROJECT_ID\u003c/var\u003e with the project ID of\n your [fleet host project](/anthos/fleet-management/docs/fleet-concepts#fleet-host-project).\n This is the project ID that was configured in the `gkeconnect` section of your\n [cluster configuration file](/anthos/clusters/docs/bare-metal/1.13/reference/cluster-config-ref#gkeconnect-projectid).\n3. Enroll the cluster with the Anthos On-Prem API:\n\n ### User cluster\n\n Be sure to scroll over if needed to fill in the\n \u003cvar translate=\"no\"\u003eADMIN_CLUSTER_NAME\u003c/var\u003e placeholder for the\n `--admin-cluster-membership` flag.\n\n ```\n gcloud container bare-metal clusters enroll USER_CLUSTER_NAME \\\n --project=FLEET_HOST_PROJECT_ID \\\n --admin-cluster-membership=projects/FLEET_HOST_PROJECT_ID/locations/global/memberships/ADMIN_CLUSTER_NAME \\\n --location=LOCATION\n ```\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eUSER_CLUSTER_NAME\u003c/var\u003e: The name of the user cluster\n that you want to enroll.\n\n - \u003cvar translate=\"no\"\u003eFLEET_HOST_PROJECT_ID\u003c/var\u003e The project ID of\n your fleet host project.\n\n - \u003cvar translate=\"no\"\u003eADMIN_CLUSTER_NAME\u003c/var\u003e: The admin cluster\n that manages the user cluster. The admin cluster name is the last\n segment of the fully-specified cluster name that uniquely identifies\n the cluster in Google Cloud.\n\n - \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e: The Google Cloud region in which\n the Anthos On-Prem API runs. Specify `us-west1` or another\n [supported region](/anthos/clusters/docs/bare-metal/1.13/reference/supported-regions-on-prem-api).\n The region can't be changed after the cluster is enrolled. In addition\n to setting the region where the Anthos On-Prem API runs, this is the\n region in which the following is stored:\n\n - The user cluster metadata that the Anthos On-Prem API needs to manage the cluster lifecycle\n - The Cloud Logging and Cloud Monitoring data of system components\n - The Admin Audit log created by Cloud Audit Logs\n\n ### Admin cluster\n\n ```\n gcloud container bare-metal admin-clusters enroll ADMIN_CLUSTER_NAME \\\n --project=FLEET_HOST_PROJECT_ID \\\n --admin-cluster-membership=projects/FLEET_HOST_PROJECT_ID/locations/global/memberships/ADMIN_CLUSTER_NAME \\\n --location=LOCATION\n ```\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eADMIN_CLUSTER_NAME\u003c/var\u003e: The name of the admin cluster\n that you want to enroll.\n\n - \u003cvar translate=\"no\"\u003eFLEET_HOST_PROJECT_ID\u003c/var\u003e The project ID of\n your fleet host project.\n\n The \u003cvar translate=\"no\"\u003eADMIN_CLUSTER_NAME\u003c/var\u003e and\n \u003cvar translate=\"no\"\u003eFLEET_HOST_PROJECT_ID\u003c/var\u003e are used to form the\n fully-specified cluster name for the `--admin-cluster-membership`\n flag.\n - \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e: The Google Cloud region in which\n the Anthos On-Prem API runs. Specify `us-west1` or another\n [supported region](/anthos/clusters/docs/bare-metal/1.13/reference/supported-regions-on-prem-api).\n The region can't be changed after the cluster is enrolled. In addition\n to setting the region where the Anthos On-Prem API runs, this is the\n region in which the following is stored:\n\n - The cluster metadata that the Anthos On-Prem API needs to manage the cluster lifecycle\n - The Cloud Logging and Cloud Monitoring data of system components\n - The Admin Audit log created by Cloud Audit Logs\n4. After the cluster is enrolled, you can use the following commands to\n get information about your clusters:\n\n ### User cluster\n\n - To describe a user cluster:\n\n ```\n gcloud container bare-metal clusters describe USER_CLUSTER_NAME \\\n --project=FLEET_HOST_PROJECT_ID \\\n --location=LOCATION\n ```\n - To list your user clusters:\n\n ```\n gcloud container bare-metal clusters list \\\n --project=FLEET_HOST_PROJECT_ID \\\n --location=LOCATION\n ```\n\n ### Admin cluster\n\n - To describe an admin cluster:\n\n ```\n gcloud container bare-metal admin-clusters describe ADMIN_CLUSTER_NAME \\\n --project=FLEET_HOST_PROJECT_ID \\\n --location=LOCATION\n ```\n - To list your admin clusters:\n\n ```\n gcloud container bare-metal admin-clusters list \\\n --project=FLEET_HOST_PROJECT_ID \\\n --location=LOCATION\n ```\n\nConnect to the cluster\n----------------------\n\nAfter the cluster is enrolled with the Anthos On-Prem API, you need to choose\nand configure an authentication method so that you can\n[manage the cluster from the Google Cloud console](/anthos/clusters/docs/bare-metal/1.13/how-to/anthos-ui).\nThe authentication method that you select also controls access to the cluster\nfrom the command line. For more information, see the following:\n\n- [Connecting to registered clusters with the Connect gateway](/anthos/multicluster-management/gateway)\n- [GKE Identity Service](/anthos/identity)"]]
