Stay organized with collections Save and categorize content based on your preferences.

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 user 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 use Connect gateway to connect to registered clusters outside Google Cloud with their Google Cloud identity using gcloud. The Google Groups feature for authentication is not currently supported when accessing Anthos clusters outside Google Cloud using the Google Cloud console.

The configuration steps in this documentation let you set up access control with Google Groups for Anthos clusters on VMware and Anthos on bare metal from Anthos 1.13 onwards. If you are using GKE clusters, follow the instructions in Configure Google Groups for RBAC.

If you want to use this feature with attached clusters or other Anthos clusters environments, please contact Cloud Customer Care or the Connect gateway team.

This feature uses Google Groups associated with Google Workspace only. Groups with a suffix are not supported.

How it works

As described in the overview, it's often useful to be able to give users access to clusters on the basis of their membership of Google 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 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 Google Kubernetes Engine Workloads or Object Browser pages in the Google Cloud 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 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:

    • The latest version of the Google Cloud CLI the command line tool for interacting with Google Cloud.
    • The Kubernetes command line tool, kubectl, for interacting with your clusters.

    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 the Anthos clusters on VMware or Anthos clusters on bare metal that you're configuring are version 1.13 or higher. Version 1.13 includes the required minimum version of Anthos Identity Service to use Google groups. For more information on how to upgrade clusters, see Upgrading Anthos clusters for VMWare and Upgrading Anthos clusters on bare metal.

  • You must add your groups as members of the gke-security-groups group. It is recommended to avoid adding individual users as members of gke-security-groups. Users who'd like to have the Google Groups feature should use the same domain name as that of the group.

  • Anthos Identity Service needs to call the Google Identity API from your cluster. Check if your network policy requires outbound traffic to go through a proxy.

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 Google Cloud 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 feature uses Anthos Identity Service to get user and group information from a variety of identity providers, including Google. 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 feature requires version 1.13 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


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

Configure Google Groups

Based on how you have setup Anthos Identity Service, determines the way in which Google Groups feature needs to be configured.

If you're using Anthos Identity Service for the first time, you can choose between configuring Google Groups at Fleet level (recommended) or Per-cluster setup.

If you're not a first time user of Anthos Identity Service, keep in mind one of the following:

  • If you have already set up Anthos Identity Service for another identity provider at fleet level, the Google Groups feature is enabled for you by default. See the Fleet section below for more details and any additional setup you may require.
  • If you have already set up Anthos Identity Service for another identity provider on a per-cluster basis, see the Per-cluster section below for instructions to update your configuration for the Google Groups feature.


If you have not previously set up Anthos Identity Service for a fleet, follow the instructions in Configure clusters for Anthos Identity Service. Specify only the following configuration in your auth-config.yaml file:

  - name: google-authentication-method
      disable: false

If you have already configured Anthos Identity Service at fleet-level with another identity provider (such as Microsoft AD FS or Okta), the Connect gateway Google Groups feature is already enabled for you by default on configured clusters, provided that the Google identity provider is reachable without the need to use a proxy.

Configuring Google Groups access using a proxy

If you need to access the Google identity provider through a proxy, use a proxy field in your auth-config.yaml file. You might need to set this if, for example, your cluster is in a private network and needs to connect to a public identity provider. You must add this configuration even if you have already configured Anthos Identity Service for another provider.

To configure the proxy, here's how you can update the authentication section of the existing configuration file auth-config.yaml.

  - name: google-authentication-method
      disable: false
    proxy: PROXY_URL


  • disable (optional) denotes if you want to opt in or out of the Google Groups feature for clusters. This value is set to false by default. If you'd like to opt out of this feature, you can set it to true.

  • PROXY_URL (optional) is the proxy server address to connect to the Google identity. For example: http://user:password@

Apply the configuration

To apply the configuration to a cluster, run the following command:

gcloud container fleet identity-service apply \
--membership=CLUSTER_NAME \


CLUSTER_NAME is your cluster's unique membership name within the fleet.

Once applied, this configuration is managed by the Anthos Identity Service controller. Any local changes made to Anthos Identity Service client configuration is reconciled back by the controller to the configuration specified in this setup.

Per cluster

To configure your cluster to use Anthos Identity Service with the Google Groups feature, you need to update the cluster's Anthos Identity Service ClientConfig. This is a Kubernetes custom resource type (CRD) used for cluster configuration. Each Anthos cluster has a ClientConfig resource named default in the kube-public namespace that you update with your configuration details.

To edit the configuration, use the following command.

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

where USER_CLUSTER_KUBECONFIG is the path to the kubeconfig file of your cluster.

If there are multiple contexts in the kubeconfig, the current context is used. You might need to reset the current context to the correct cluster before running the command.

Here's an example of how you can update the ClientConfig with a new authentication method having a configuration of type google to enable Google Groups feature. If the internalServer field is empty, make sure it's set to https://kubernetes.default.svc, as shown below.

  - google:
    name: google-authentication-method
    proxy: PROXY_URL
  internalServer: https://kubernetes.default.svc


CLUSTER_IDENTIFIER (required) denotes the membership details of your cluster. You can retrieve your cluster's membership details using the command:

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get memberships membership -o yaml


USER_CLUSTER_KUBECONFIG is the path to the kubeconfig file for the cluster. In the response, refer to the field to retrieve the cluster's membership details.

Here's an example response showing a cluster's membership details:

id: //

which corresponds to the following format: //

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.

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.

In the following example, you'll see how to can grant members of the cluster-admin-team group cluster-admin permissions on the cluster, save the policy file as /tmp/admin-permission.yaml and apply it to the cluster associated with the current context. Be sure to also include the cluster-admin-team group under the gke-security-groups group.

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 --kubeconfig=KUBECONFIG_PATH -f /tmp/admin-permission.yaml

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

What's next?