Configure a cluster to be managed by the Anthos On-Prem API

The Anthos On-Prem API lets you manage on-premises cluster lifecycles by using the Google Cloud console, the Google Cloud CLI, or Terraform. When you create a cluster with these tools, the API stores cluster metadata in your chosen Google Cloud region. If you create clusters with bmctl, you must enroll them in the Anthos On-Prem API to view details and manage their lifecycles through these interfaces.

Enrolling a cluster is separate from registering it to a fleet. All Google Distributed Cloud clusters automatically register to a fleet host project at creation. In the Google Cloud console, registered clusters managed by the Anthos On-Prem API show as Bare metal in the Type column, whereas unenrolled clusters appear as External.

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.

To view your fleet clusters:

  1. In the console, go to the GKE clusters page.
    Go to GKE clusters
  2. Select the Google Cloud project.
    • 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 cluster

To enroll a cluster for management by the Anthos On-Prem API:

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

    gcloud components update

  2. Enable the Anthos On-Prem API in your fleet host project:

    gcloud services enable \
    --project FLEET_HOST_PROJECT_ID \
    gkeonprem.googleapis.com

    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.

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

    gcloud container bare-metal clusters enroll USER_CLUSTER_NAME  \
  --project=FLEET_HOST_PROJECT_ID \
  --admin-cluster-membership=projects/FLEET_HOST_PROJECT_ID/locations/global/memberships/ADMIN_CLUSTER_NAME \
  --location=LOCATION

    Replace the following:

    • 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
      • The Admin Audit log created by Cloud Audit Logs

    Admin cluster

    Be sure to scroll over if needed to fill in the ADMIN_CLUSTER_NAME placeholder for the --admin-cluster-membership flag.

    gcloud container bare-metal admin-clusters enroll ADMIN_CLUSTER_NAME \
  --project=FLEET_HOST_PROJECT_ID \
  --admin-cluster-membership=projects/FLEET_HOST_PROJECT_ID/locations/global/memberships/ADMIN_CLUSTER_NAME \
  --location=LOCATION

    Replace the following:

    • 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

  4. After the cluster is enrolled, you can use the following commands to get information about your clusters:

    User cluster

    • To describe a user cluster:
    gcloud container bare-metal clusters describe USER_CLUSTER_NAME \
   --project=FLEET_HOST_PROJECT_ID \
   --location=LOCATION
    • To list your user clusters:
    gcloud container bare-metal clusters list \
   --project=FLEET_HOST_PROJECT_ID \
   --location=-

    When you set --location=-, that means to list all clusters in all regions. If you need to scope down the list, set --location to the region you specified when you enrolled the cluster.

    Admin cluster

    • To describe an admin cluster:
    gcloud container bare-metal admin-clusters describe ADMIN_CLUSTER_NAME \
   --project=FLEET_HOST_PROJECT_ID \
   --location=LOCATION
    • To list your admin clusters:
    gcloud container bare-metal admin-clusters list \
   --project=FLEET_HOST_PROJECT_ID \
   --location=-

    When you set --location=-, that means to list all clusters in all regions. If you need to scope down the list, set --location to the region you specified when you enrolled the cluster.

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: