Registering a cluster

This page describes how to manually register your Kubernetes clusters with Google Cloud.

Note: Anthos clusters on VMware and Anthos clusters on AWS clusters are registered automatically at cluster creation. However, you might need to manually register these clusters if you unregistered a cluster by mistake, or if you want to change a cluster's membership to a different environ.

Before you begin

Before you register your Kubernetes clusters with Google Cloud for the first time, complete the following Network, Google Cloud, and Kubernetes prerequisites:

1. Ensure network connectivity. If you are registering a GKE cluster running on Google Cloud, you have this by default.

2. Google Cloud configurations

   • Install Cloud SDK version 281.0.0 or higher.
   • Authorize gcloud to access Google Cloud.
   • Grant the required Google Cloud IAM roles to the user registering the cluster.
   • Enable the required APIs in your Google Cloud project.
   • Use gcloud to create a Google Cloud service account. If you choose to use the Cloud Console to register Anthos on Google Cloud clusters, by default, a service account is created for you, so you don't need to create one in advance.

3. Kubernetes configurations

   • Install kubectl.
   • Grant the cluster-admin RBAC role to the user registering the cluster.

Register a cluster

Note: When you register a cluster, Feature Authorizer and Metering are enabled by default. You can't disable these features while your clusters are registered with Connect. For more information about what these features do, see What uses Connect.

gcloud

Register a GKE cluster

While registering the cluster, you can configure the Connect Agent to either use Workload Identity or use a Google Cloud Service Account.

Registering a GKE cluster using Workload Identity (recommended)

Note: Ensure that Workload Identity is enabled before you try to register a cluster using this approach. Registering a cluster using Workload Identity without having GKE Workload Identity enabled on the cluster can lead to inconsistencies on how identity is asserted by workloads in the cluster, and is not a supported configuration.

1. Determine if Workload Identity is enabled on your GKE cluster

   Run the following command to list which Workload Identity pool your cluster is a member of

   gcloud container clusters describe GKE_CLUSTER --format="value(workloadIdentityConfig.workloadPool)"
   

   Replace the following:

   • GKE_CLUSTER: the name of the GKE cluster for the current project.

   If you see a result similar to the following then Workload Identity is already enabled on your GKE cluster and you can proceed directly to "Register the Cluster" below.

   GKE_PROJECT_ID.svc.id.goog

   If there are no results, then Workload Identity is not enabled on the GKE cluster. Please continue to enable Workload Identity on your GKE cluster before proceeding to register the cluster.

2. Enable Workload Identity

   Carefully follow the linked instructions to enable GKE Workload Identity. Enabling GKE Workload Identity changes authentication behavior for any new node pools created after it is enabled, which can affect applications that rely on service accounts attached to Compute Engine instances in the node pool.

3. Register the Cluster

   Run either of the following commands to register the cluster:

   gcloud beta container hub memberships register MEMBERSHIP_NAME \
    --gke-uri=GKE_URI \
    --enable-workload-identity
   

   or

   gcloud beta container hub memberships register MEMBERSHIP_NAME \
    --gke-cluster=GKE_CLUSTER \
    --enable-workload-identity
   

   Replace the following:

   • MEMBERSHIP_NAME: the membership name that you choose to uniquely represent the cluster being registered on the Hub.
   • GKE_URI: the URI of the GKE cluster, for example: https://container.googleapis.com/v1/projects/my-gke-project/locations/us-central1-a/clusters/my-gke-cluster. You can obtain the URI by running gcloud container clusters list --uri.
   • GKE_CLUSTER: the location/name of the GKE cluster from the current project. The location can be a zone or a region, for example: us-central1-a/my-gke-cluster.

Registering a GKE cluster using Service Account

Run either of the following commands:

gcloud container hub memberships register MEMBERSHIP_NAME \
   --gke-uri=GKE_URI \
   --service-account-key-file=SERVICE_ACCOUNT_KEY_PATH

or

gcloud container hub memberships register MEMBERSHIP_NAME \
   --gke-cluster=GKE_CLUSTER \
   --service-account-key-file=SERVICE_ACCOUNT_KEY_PATH

Replace the following:

• MEMBERSHIP_NAME: the membership name that you choose to uniquely represent the cluster being registered on the Hub.
• SERVICE_ACCOUNT_KEY_PATH: the local filepath to the service account's private key JSON file downloaded as part of Prerequisites. This service account key is stored as a secret named creds-gcp in the gke-connect namespace.
• GKE_URI: the URI of the GKE cluster, for example: https://container.googleapis.com/v1/projects/my-gke-project/locations/us-central1-a/clusters/my-gke-cluster. You can obtain the URI by running gcloud container clusters list --uri.
• GKE_CLUSTER: the location/name of the GKE cluster from the current project. The location can be a zone or a region, for example: us-central1-a/my-gke-cluster.

Register any other cluster

These instructions apply to non-GKE, Anthos clusters on AWS, Anthos clusters on VMware, and any other Anthos clusters.

Run the following command:

 gcloud container hub memberships register MEMBERSHIP_NAME \
   --context=KUBECONFIG_CONTEXT \
   --kubeconfig=KUBECONFIG_PATH \
   --service-account-key-file=SERVICE_ACCOUNT_KEY_PATH

Replace the following:

• MEMBERSHIP_NAME: the membership name that you choose and that is used to uniquely represent the cluster being registered on the Hub.
• SERVICE_ACCOUNT_KEY_PATH: the local filepath to the service account's private key JSON file downloaded as part of Prerequisites. This service account key is stored as a secret named creds-gcp in the gke-connect namespace.
• KUBECONFIG_CONTEXT: the cluster context of the cluster being registered as it appears in the kubeconfig file. You can get this value from the command line by running kubectl config current-context.
• KUBECONFIG_PATH: the local filepath where your kubeconfig containing an entry for the cluster being registered is stored. This defaults to $KUBECONFIG if that environment variable is set; otherwise, this defaults to $HOME/.kube/config.

Console

Register an Anthos on Google Cloud cluster

These instructions apply to GKE clusters on Google Cloud in projects that have enabled Anthos.

To register a cluster:

1. In the Google Cloud Console, go to the Anthos Clusters page. This page shows all your registered clusters.

   Go to the Anthos Clusters page

2. Click Register existing cluster.

3. Click Register next to the unregistered cluster that you want to add to your environ.

4. Specify the service account that you want to use when registering the cluster. We recommend keeping the default behavior and creating a new service account.

   • If you select Create a new service account:
     • Specify a Service account ID to identify your new service account.
     • Choose if you want to download its service account key as a JSON file. We recommend keeping the default behavior and downloading the key because you won't be able to download it later.
   • If you select Use existing service account, paste in the account's service account key in JSON format.

5. Optional: Specify a new membership name for your cluster. By default, a cluster's membership name is its current name. However, if your cluster's name is not unique within your project, you must specify a new unique membership name because all clusters require a unique identifier within their environ.

6. To register your cluster, click Submit.

Register any other cluster

These instructions apply to non-GKE, Anthos clusters on AWS, Anthos clusters on VMware, and any other GKE or Anthos clusters.

To register a cluster:

1. In the Google Cloud Console, go to the Anthos Clusters page. This page shows all your registered clusters.

   Go to the Anthos Clusters page

2. Click Register existing cluster.

3. Click Add external cluster.

   Note: You can also access the same functionality by clicking Register cluster on your GKE dashboard if you're an Anthos user.

4. Enter the name of the cluster that you want to register in the Cluster name field.

5. Optional: Add Google Cloud labels to your cluster.

6. Click Generate registration command.

7. In Cloud Shell or wherever you have saved your service account credentials, edit and run the gcloud command that is displayed on the page. You need to specify the following values:

   • The CLUSTER_CONTEXT is the cluster's context as it appears in the kubeconfig file. You can get this value from the command line by running kubectl config current-context.
   • The KUBECONFIG_PATH is the local filepath where your kubeconfig file is stored. This defaults to $KUBECONFIG if that environment variable is set; otherwise, it defaults to $HOME/.kube/config.
   • The LOCAL_KEY_PATH is the path to your service account key file.

   Running this command deploys the Connect Agent in your user cluster. When the Connect Agent connects to Google Cloud and your cluster is registered, a success message is displayed on the page.

8. Click Set labels, or click Skip if you didn't set any labels.

Advanced registration options (command line only)

Download the Connect Agent manifest

To download the Connect Agent installation manifest without deploying the agent, for example if you want to examine or edit the manifest before installation, pass in the --manifest-output-file flag to the gcloud container hub memberships register command. For example:

--manifest-output-file=[MANIFEST_FILE_PATH]

where [MANIFEST_FILE_PATH] is the local filepath where you want the Connect Agent installation manifest to be stored.

Using this option will not deploy the Connect Agent into the cluster. To deploy the Connect Agent, manually apply the downloaded manifest to your cluster.

Using a proxy server

To configure a proxy server, pass in the --proxy flag to gcloud container hub memberships register command. For example:

--proxy=[URL]

where [URL] is the proxy address.

The Connect Agent supports CONNECT-based HTTP and HTTPS proxies only, and accepts IP addresses and hostnames. Be sure to specify the protocol corresponding to the proxy type in the URL. For example, to pass in an HTTPS hostname:

--proxy=https://mycorpproxy.com:443

Unless you specify otherwise, Connect Agent uses port 3128 for the proxy.

If your proxy requires authorization, ensure that you pass in your credentials, such as:

--proxy=http://user:password@10.10.10.10:8888

Installing Connect Agent in a cluster with Windows and Linux nodes

The Connect Agent has to run on a Linux node. If you are installing in a mixed cluster with both Linux and Windows nodes, you can ensure that the Connect Agent is deployed on to a Linux node by adding an appropriate node selector to the deployment definition.

Run the following command to update the deployment with the appropriate node selector:

kubectl patch deployment \
 $(kubectl get deployment -o=jsonpath='{.items[*].metadata.name}' -n gke-connect) \
 -p '{"spec":{"template":{"spec":{"nodeSelector":{"kubernetes.io/os":"linux"}}}}}' -n gke-connect

To validate that the update succeeded run the following command:

kubectl get deployment -o=jsonpath='{.items[].spec.template.spec.nodeSelector}' -n gke-connect

The command should return:

{"kubernetes.io/os":"linux"}

What's next

• Viewing registered clusters
• Logging in to a registered cluster
• Troubleshooting