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.
Log in with your Google account:
gcloud auth login --no-browser
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.
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.
Grant the gkeonprem.admin role to your service account:
Set up your
application default credentials
to use the service account. This ensures that the gcloud CLI
uses the service account you created previously.
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.
[[["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-08-25 UTC."],[[["\u003cp\u003eUser clusters created with \u003ccode\u003egkectl\u003c/code\u003e need to be configured to work with the Anthos On-Prem API to be managed via the Google Cloud console.\u003c/p\u003e\n"],["\u003cp\u003eConfiguring a \u003ccode\u003egkectl\u003c/code\u003e-created user cluster to use the console is done with the \u003ccode\u003egkectl enroll cluster\u003c/code\u003e command.\u003c/p\u003e\n"],["\u003cp\u003eThe user cluster to be configured must be on version 1.11 or higher, and registered with a fleet.\u003c/p\u003e\n"],["\u003cp\u003eThe process of configuring requires the creation of a service account, enabling the Anthos On-Prem API, and granting the appropriate permissions.\u003c/p\u003e\n"],["\u003cp\u003eRunning the \u003ccode\u003egkectl enroll cluster\u003c/code\u003e command requires the name of the user cluster and the path to the admin cluster's \u003ccode\u003ekubeconfig\u003c/code\u003e file.\u003c/p\u003e\n"]]],[],null,["# Configure a user cluster to be managed by the Anthos On-Prem API\n\n\u003cbr /\u003e\n\nGoogle Distributed Cloud user clusters created using `gkectl` aren't\nconfigured to work with the Anthos On-Prem API, which is the\nGoogle Cloud-hosted API that gets enabled automatically when you create user\nclusters in the Google Cloud console. To use the console to manage the\nlifecycle of user clusters that were created using `gkectl`, you need to\nconfigure the cluster using the `gkectl enroll cluster` command.\n\nRequirements\n------------\n\nThe user cluster must meet the following requirements:\n\n- Version 1.11 or higher.\n- Registered with a [fleet](/anthos/fleet-management/docs), which is done automatically when the cluster is created as of version 1.8.\n- If your organization has set up\n [an allowlist](/anthos/clusters/docs/on-prem/1.11/how-to/firewall-rules) that lets traffic from\n Google APIs and other addresses pass through your proxy server, add the\n following to the allowlist:\n\n - gkeonprem.googleapis.com\n - gkeonprem.mtls.googleapis.com\n\nEnroll a user cluster\n---------------------\n\nRun the following steps on your admin workstation.\n\n1. Log in with your Google account:\n\n gcloud auth login --no-browser\n\n2. Create a service account to authorize `gkectl` to enroll the cluster:\n\n gcloud iam service-accounts create \u003cvar translate=\"no\"\u003eSA_NAME\u003c/var\u003e \\\n --project \u003cvar translate=\"no\"\u003eSA_PROJECT_ID\u003c/var\u003e\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eSA_NAME\u003c/var\u003e 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`.\n - \u003cvar translate=\"no\"\u003eSA_PROJECT_ID\u003c/var\u003e 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.\n3. Create a JSON key for your service account:\n\n gcloud iam service-accounts keys create \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-n\"\u003eSA_NAME\u003c/span\u003e\u003c/var\u003e-key.json \\\n --iam-account=\u003cvar translate=\"no\"\u003eSA_NAME\u003c/var\u003e@\u003cvar translate=\"no\"\u003eSA_PROJECT_ID\u003c/var\u003e.iam.gserviceaccount.com\n\n4. 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 ID of the\n [fleet host project](/anthos/fleet-management/docs/fleet-concepts#fleet-host-project).\n This must be the same Google Cloud project that your admin and user\n clusters are registered to, which you specify in the\n [gkeConnect.projectID](/anthos/clusters/docs/on-prem/1.11/how-to/user-cluster-configuration-file#gkeconnect-projectid-field)\n field in the cluster configuration file.\n5. Grant the `gkeonprem.admin` role to your service account:\n\n gcloud projects add-iam-policy-binding \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-n\"\u003eFLEET_HOST_PROJECT_ID\u003c/span\u003e\u003c/var\u003e \\\n --member \"serviceAccount:\u003cvar translate=\"no\"\u003eSA_NAME\u003c/var\u003e@\u003cvar translate=\"no\"\u003eSA_PROJECT_ID\u003c/var\u003e.iam.gserviceaccount.com\" \\\n --role \"roles/gkeonprem.admin\"\n\n6. Set up your\n [application default credentials](/authentication/application-default-credentials)\n to use the service account. This ensures that the gcloud CLI\n uses the service account you created previously.\n\n export GOOGLE_APPLICATION_CREDENTIALS=\u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-n\"\u003ePATH_TO_SA_KEY\u003c/span\u003e\u003c/var\u003e/\u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-n\"\u003eSA_NAME\u003c/span\u003e\u003c/var\u003e-key.json\n\n7. Run the `gkectl enroll cluster` command. Replace the following:\n\n - \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e with the name of the user cluster.\n - \u003cvar translate=\"no\"\u003eADMIN_CLUSTER_KUBECONFIG\u003c/var\u003e with the path of your admin cluster's `kubeconfig` file.\n\n gkectl enroll cluster --cluster-name=\u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e \\\n --kubeconfig \u003cvar translate=\"no\"\u003eADMIN_CLUSTER_KUBECONFIG\u003c/var\u003e\n\n If you have more than one user cluster in a project that you want to enroll,\n you can use the same service account and key and just run\n `gkectl enroll cluster` for each cluster."]]
