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

Google Distributed Cloud user clusters created using gkectl aren't configured to work with the Anthos On-Prem API, which is the Google Cloud-hosted API that gets enabled automatically when you create user clusters in the Google Cloud console. To use the console to manage the lifecycle of user clusters that were created using gkectl, you need to configure the cluster using the gkectl enroll cluster command.

Requirements

The user cluster must meet the following requirements:

  • Version 1.11 or higher.
  • Registered with a fleet, which is done automatically when the cluster is created as of version 1.8.

  • 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

Enroll a user cluster

Run the following steps on your admin workstation.

  1. Log in with your Google account:

    gcloud auth login --no-browser

  2. Create a service account to authorize gkectl to enroll the cluster:

    gcloud iam service-accounts create SA_NAME \
    --project SA_PROJECT_ID

    Replace the following:

    • SA_NAME with the name you want to give to the service account. You might want to use a name that describes the purpose of the service account, such as enrollment-sa.
    • SA_PROJECT_ID the ID of the parent project of your service account. The project that you create the service account in can be the same or a different project where the service account is used.

  3. Create a JSON key for your service account:

    gcloud iam service-accounts keys create SA_NAME-key.json \
   --iam-account=SA_NAME@SA_PROJECT_ID.iam.gserviceaccount.com

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

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

    Replace FLEET_HOST_PROJECT_ID with the ID of the fleet host project. This must be the same Google Cloud project that your admin and user clusters are registered to, which you specify in the gkeConnect.projectID field in the cluster configuration file.

  5. Grant the gkeonprem.admin role to your service account:

    gcloud projects add-iam-policy-binding FLEET_HOST_PROJECT_ID \
    --member "serviceAccount:SA_NAME@SA_PROJECT_ID.iam.gserviceaccount.com" \
    --role "roles/gkeonprem.admin"

  6. Set up your application default credentials to use the service account. This ensures that the gcloud CLI uses the service account you created previously.

    export GOOGLE_APPLICATION_CREDENTIALS=PATH_TO_SA_KEY/SA_NAME-key.json

  7. Run the gkectl enroll cluster command. Replace the following:

    • CLUSTER_NAME with the name of the user cluster.
    • ADMIN_CLUSTER_KUBECONFIG with the path of your admin cluster's kubeconfig file.
    gkectl enroll cluster --cluster-name=CLUSTER_NAME \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG

    If you have more than one user cluster in a project that you want to enroll, you can use the same service account and key and just run gkectl enroll cluster for each cluster.