Set up the Connect gateway with Google Groups

This guide is for platform administrators who need to set up the Connect gateway for use by their project's users and service accounts, using Google Groups for authorization. Before reading this guide, you should be familiar with the concepts in our overview. To authorize individual accounts, see the default setup.

This setup allows users to both use the Connect gateway directly, and to connect to registered clusters outside Google Cloud with their Google Cloud identity in the console, as described in Logging in to a cluster from the console.

The Connect gateway's Google Group functionality is supported for Anthos clusters on VMware only in this preview release. If you want to use this feature with attached clusters or other Anthos clusters environments, please contact Cloud Customer Care.

This feature uses Google Groups associated with Google Workspace only. Groups with a suffix are not supported. Authorization based on indirect group membership is not supported.

How it works

As described in the overview, it's often useful to be able to give users and services access to clusters on the basis of their membership of security groups. Authorizing based on group membership means you don't have to set up separate authorization for each account, making policies simpler to manage and easier to audit. So, for example, you can easily share cluster access to a team, removing the need to manually add/remove individual users from clusters when they join or leave the team. With some additional setup using Anthos Identity Service, you can configure the Connect gateway to get Google Group membership information for each user or service that logs into the cluster. You can then use this groups information in your access control policies.

The following shows the typical flow for a user authenticating to and running commands against a cluster with this service enabled:

Diagram showing the gateway Google Groups flow

  1. The user logs in using their Google identity and, if they plan to use the cluster from the command line, gets the cluster's gateway kubeconfig as described in Using the Connect gateway.
  2. The user sends a request by running a kubectl command or opening the GKE Workload or Object Browser pages in the console.
  3. The request is received by the Connect service, which performs an authorization check with IAM.
  4. The Connect service forwards the request to the Connect Agent running on the cluster. The request is accompanied with the user's credential information for use in authentication and authorization on the cluster.
  5. The Connect Agent forwards the request to the Kubernetes API server.
  6. The Kubernetes API server forwards the request to Anthos Identity Service, which validates the request.
  7. Anthos Identity Service calls the Cloud Identity API to get the list of groups that contain
  8. Anthos Identity Service returns the user and group information to the Kubernetes API server. The Kubernetes API server can then use this information to authorize the request based on the cluster's configured RBAC policies.

Before you begin

  • Ensure that you have the following command line tools installed:

    If you are using Cloud Shell as your shell environment for interacting with Google Cloud, these tools are installed for you.

  • Ensure that you have initialized the gcloud CLI for use with your project.

  • This guide assumes that you have roles/owner in your project. If you are not a project owner, you may need additional permissions to perform some of the setup steps.

  • Ensure that your organization has a Google Workspace edition that allows you to create a Google LDAP client on the Google Admin console. Google Workspace editions that support creating LDAP clients are Business Plus, Enterprise, Education Fundamentals, Standard, Teaching and Learning Upgrade, and Plus. For more details, see the Google Workspace documentation.

  • Ensure that the Anthos clusters on VMware that you're configuring are version 1.8 or higher. Version 1.8 includes the required minimum version of Anthos Identity Service to use security groups. You can find out how to upgrade clusters in our Upgrading guide.

  • Anthos Identity Service needs to call the Cloud Identity API from your cluster to get group information for users. Check if your network policy requires outbound traffic like this to go through a proxy—using a proxy is not supported in this preview release.

Enable APIs

To add the gateway to your project, enable the Connect gateway API and its required dependency APIs. If your users only want to authenticate to clusters using the console, you don't need to enable, but do need to enable the remaining APIs.

gcloud services enable --project=${PROJECT_ID}  \ \ \ \ \

Set up Anthos Identity Service

Connect gateway's Google Groups support uses Anthos Identity Service to get group membership information for users and services. You can find out more about this service in Introducing Anthos Identity Service.

Ensure Anthos Identity Service is installed

Anthos Identity Service is installed by default on Anthos clusters from version 1.7 onwards (though Google Groups support requires version 1.8 or higher). You can confirm that it is installed correctly on your cluster by running the following command:

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get all -n anthos-identity-service

...where USER_CLUSTER_KUBECONFIG is the path to the kubeconfig file for the cluster.

Get login details

To get Google Groups information for users, Anthos Identity Service needs to authenticate to the Cloud Identity API and retrieve user details. To configure this, you need to download the LDAP client secret from the Google Admin Console. You may need help from your company's Google Admin for this step.

  1. Ensure that you are logged in to your Google Workspace or Cloud Identity account in
  2. Log in to the Google Admin console with the account.
  3. Select Apps - LDAP from the left menu.
  4. Click Add client.
  5. Add your chosen client name and description and click Continue.
  6. In the Access permissions section, ensure that the client has the appropriate permissions to read your directory and access user information.
  7. Download the client certificate and complete client creation. Downloading the certificate also downloads the corresponding key.
  8. Ensure the service status for the LDAP client is set to ON in the Google Admin console.

Create the Kubernetes Secret

To make the LDAP login information available to Anthos Identity Service, you need to create a Kubernetes Secret resource, with the login details you got in the previous step.


The simplest way to create and apply the Secret is to use kubectl create secret, as follows:

kubectl create secret tls SECRET_NAME \
--cert=path/to/cert/file \

...where SECRET_NAME is the name you have chosen for the Secret, and cert and key specify the paths to the certificate and key files you downloaded in the previous section. Ensure you create the Secret in the anthos-identity-service namespace.


To create the Secret from a config file:

  1. Run the following commands in the relevant directory to base64 encode the certificate and key, substituting the file names of your downloaded certificate and key. Keep the terminal output to copy and paste in when creating the Secret in the next step.

    cat CERTIFICATE_FILENAME.crt | base64
    cat KEY_FILENAME.key | base64
  2. Create a secret.yaml config file with the details for the Secret, as in the following example. Replace the TLS certificate and key values with the encoded certificate and key values you got in the previous step. The type should be, which is the Secret type for logins using a client private key and client certificate, and the namespace should be anthos-identity-service. SECRET_NAME is the name you have chosen for this Secret.

    apiVersion: v1
    kind: Secret
      name: SECRET_NAME
      namespace: anthos-identity-service
    type:            # Make sure the type is correct
      # the data is abbreviated in this example
      tls.crt: |
           MIIC2DCCAcCgAwIBAgIBATANBgkqh ...
      tls.key: |
           MIIEpgIBAAKCAQEA7yn3bRHQ5FHMQ ...
  3. Use kubectl apply to create the Secret from your file:

    kubectl apply -f ./secret.yaml

Configure the cluster

Anthos Identity Service uses a Kubernetes custom resource type to configure your clusters called ClientConfig, with configuration it requires to run a Google group membership query. Your ClientConfig configuration also includes the secret name and namespace from the Kubernetes Secret that you created and applied in the previous section. This allows Anthos Identity Service to authenticate to the Cloud Identity API.

To apply the configuration to your cluster, edit the KRM default object of type clientconfig in the kube-public namespace:

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG -n kube-public edit clientconfig default

...where USER_CLUSTER_KUBECONFIG is the path to the kubeconfig file for the cluster. If there are multiple contexts in the kubeconfig, the current context is used. You may need to reset the current context to the correct cluster before running the command.

Add a new entry to the authentication section in the ClientConfig CR. The following shows a ClientConfig configuration example for Google Group support:

- name: connect_gateway
      namespace: anthos-identity-service
      filter: (ObjectClass=*)
internalServer: https://kubernetes.default

The internalServer field is used when using the Connect gateway to configure where to send Anthos Identity Service requests. For Anthos clusters on VMware this must be https://kubernetes.default, as in the example.

You can see a complete reference to other ClientConfig fields in the Anthos Identity Service LDAP guide.

Grant IAM roles to Google Groups

Groups need the following additional Google Cloud roles to interact with connected clusters through the gateway:

  • roles/gkehub.gatewayAdmin. This role allows group members to access the Connect gateway API.
    • If group members only need read-only access to connected clusters, roles/gkehub.gatewayReader can be used instead.
    • If group members need read/write access to connected clusters, roles/gkehub.gatewayEditor can be used instead.
  • roles/gkehub.viewer. This role allows group members to view registered cluster memberships.

You grant these roles using the gcloud projects add-iam-policy-binding command, as follows:

gcloud projects add-iam-policy-binding --member=group:GROUP_NAME@DOMAIN --role=GATEWAY_ROLE PROJECT_ID
gcloud projects add-iam-policy-binding --member=group:GROUP_NAME@DOMAIN --role=roles/gkehub.viewer PROJECT_ID


  • GROUP_NAME is the Google Group you want to grant the role
  • DOMAIN is your Google Workspace domain
  • GATEWAY_ROLE is one of roles/gkehub.gatewayAdmin, roles/gkehub.gatewayReader or gkehub.gatewayEditor.
  • PROJECT_ID is your project

You can find out more about granting IAM permissions and roles in Granting, changing, and revoking access to resources.

Grant roles for access through the console

For groups who only need to interact with connected clusters using the console, the following roles are required:

  • roles/gkehub.viewer. This role allows group members to view the clusters in the GKE console page.
  • roles/container.viewer. This role allows group members to view container resources in the console.

Configure role-based access control (RBAC) policies

Finally, each cluster's Kubernetes API server needs to be able to authorize kubectl commands that come through the gateway from your specified groups. For each cluster, you need to add an RBAC permissions policy that specifies which permissions the group has on the cluster. The following example shows granting members of the cluster-admin-team group cluster-admin permissions on the cluster, saving the policy file as /tmp/admin-permission.yaml and applying it to the cluster associated with the current context.

cat <<EOF > /tmp/admin-permission.yaml
kind: ClusterRoleBinding
  name: gateway-cluster-admin-group
- kind: Group
  kind: ClusterRole
  name: cluster-admin
# Apply permission policy to the cluster.
kubectl apply -f /tmp/admin-permission.yaml

You can find out more about specifying RBAC permissions in Using RBAC authorization.

What's next?