Accessing clusters with GKE Identity Service

GKE Identity Service is an authentication service that lets you use your organization's existing identity providers to authenticate to clusters in multiple GKE Enterprise environments, letting you use the same ID to log in to clusters on Google Cloud, on-premises, and other public clouds. This document is for developers and other GKE cluster users who need to access clusters using this service. If you need to log in to clusters using your Google Cloud ID via the Connect Gateway instead, see Using the Connect Gateway.

If you are a cluster or platform administrator who needs to set up GKE Identity Service for your organization or team, see the GKE Identity Service overview for supported cluster environments, other prerequisites, and the relevant setup guides.

Log in to clusters from the command line

To authenticate to clusters from the command line, you need to run gcloud authentication commands, using a special login configuration file provided by your cluster administrator.

Before you begin

  1. Ensure that you have the following command line tools installed:

    • The latest version of the Google Cloud CLI, which includes gcloud, the command line tool for interacting with Google Cloud. If you need to install the Google Cloud CLI, see the installation guide.
    • kubectl for running commands against Kubernetes clusters. If you need to install kubectl, see the installation guide

  2. Run the following commands to install or update the anthos-auth component:

    gcloud components update
gcloud components install anthos-auth

  3. Verify that the tool was installed successfully by running the following command:

    gcloud anthos auth version

    If a version is returned, your installation was successful.

Get the configuration file

The gcloud CLI assumes a default filename and location on your local machine for your authentication configuration file. Your administrator might copy the file to your machine for you. If you are manually provided the file and need to save it on your machine yourself, use the defaults to simplify your gcloud authentication commands.

Use the following commands to copy the authentication configuration file to the default location:

Linux

mkdir -p  $HOME/.config/google/anthos/
cp [AUTH_CONFIG_FILE] $HOME/.config/google/anthos/kubectl-anthos-config.yaml

where [AUTH_CONFIG_FILE] is the name of your authentication configuration file. For example kubectl-anthos-config.yaml.

macOS

mkdir -p  $HOME/Library/Preferences/google/anthos/
cp [AUTH_CONFIG_FILE] $HOME/Library/Preferences/google/anthos/kubectl-anthos-config.yaml

where [AUTH_CONFIG_FILE] is the name of your authentication configuration file. For example kubectl-anthos-config.yaml.

Windows

md "%APPDATA%\google\anthos"
copy [AUTH_CONFIG_FILE] "%APPDATA%\google\anthos\kubectl-anthos-config.yaml"

where [AUTH_CONFIG_FILE] is the name of your authentication configuration file. For example kubectl-anthos-config.yaml.

If you or your administrator choose to use a different filename or location (for example, if your administrator is providing the file at a secure URL), you can specify this using the --login-config flag with each of your authentication requests. See the following section for more details.

Authenticate to the cluster

Run gcloud commands to authenticate with your clusters:

  1. Run the gcloud anthos auth login command to initiate the authentication flow:

    gcloud anthos auth login \
 --cluster [CLUSTER_NAME] \
 --user [USER_NAME] \
 --login-config [AUTH_CONFIG_FILE_PATH] \
 --login-config-cert [CA_CERT_PEM_FILE] \
 --kubeconfig [CLUSTER_KUBECONFIG]

    where:

    • [CLUSTER_NAME] (optional) specifies the name of your cluster. If this flag is omitted, you are prompted to choose from the clusters that are specified in your authentication configuration file.

    • [USER_NAME] (optional) specifies the username for the credentials stored in the kubeconfig file. The default value is [CLUSTER_NAME]-anthos-default-user.

    • [AUTH_CONFIG_FILE_PATH] (optional) specifies the custom path or URL to where your authentication configuration file is stored or hosted. You can omit this parameter, if the file is in the default location. Example: --login-config /path/to/custom/authentication-config.yaml

    • [CA_CERT_PEM_FILE] (optional) specifies the path to a PEM certificate file from your CA. If your authentication configuration file is hosted securely, you can use an HTTPS connection to access the file. Example: --login-config-cert my-cert.pem

    • [CLUSTER_KUBECONFIG] (optional) specifies the custom path to your cluster's kubeconfig file. The OIDC ID tokens that are returned by your OpenID provider are stored in the kubeconfig file.

      Use this flag if your kubeconfig file resides in a location other than the default. If this flag is omitted, authentication tokens are added to the kubeconfig file in the default location. Example: --kubeconfig /path/to/custom.kubeconfig

    Examples:

    • Authenticate to specific cluster:

      gcloud anthos auth login --cluster my-production-cluster

    • Use a prompt to select which cluster to authenticate with:

      gcloud anthos auth login

      Result:

      Please use the --cluster flag to specify a cluster from the list below:
Source: $HOME/.config/google/anthos/kubectl-anthos-config.yaml
1. Cluster: projects/1000000000000/locations/global/memberships/gke-gcp-cluster ServerIP: https://104.198.180.50:440
2. Cluster: projects/1000000000000/locations/global/memberships/gke-baremetal-cluster ServerIP: https://104.198.180.51:440
3. Cluster: projects/1000000000000/locations/global/memberships/gke-onprem-cluster ServerIP: https://104.198.180.52:440
4. Cluster: projects/1000000000000/locations/global/memberships/gke-aws-cluster ServerIP: https://104.198.180.53:440

    • Use a hosted authentication configuration file:

      gcloud anthos auth login \
 --cluster my-production-cluster \
 --login-config HTTPS://my-secure-server/kubectl-anthos-config.yaml \
 --login-config-cert my-cert.pem

    • Use a prompt to select an authentication option. You can find out more about this, including an example, in Choose an authentication option below.

  2. Enter your credentials in the browser-based consent screen that opens. If this succeeds, your kubeconfig file should now contain an ID token that your kubectl commands will use to authenticate with the Kubernetes API server on your cluster.

  3. Verify that authentication was successful by running one of the kubectl commands to access a resource on your cluster. For example, if you have access to the "nodes" resource on the cluster (this access is configured by your cluster administrator), you should be able to run the following command and view the cluster's nodes:

    kubectl get nodes --kubeconfig [CLUSTER_KUBECONFIG]

For troubleshooting information related to user access, see Troubleshoot user access issues.

Choose an authentication method

If your cluster administrator has configured multiple identity providers for your cluster (for example, an OIDC provider and an LDAP server), and has not configured a default provider for your cluster, you are prompted at login to select an authentication option, as in the following example:

gcloud anthos auth login

Please select your preferred authentication option for cluster [gke-onprem-ldap]
[1] LDAP Server
[2] OIDC
[3] cancel

Please enter your numeric choice:

1

Setting Preferred Authentication option to [LDAP Server]

Enter a numeric choice, then continue to log in as described in Authenticate to the cluster above.

Your chosen authentication option is saved until either your cluster administrator changes the default provider for this cluster, or you change it yourself. To change your preferred authentication option, use the --set-preferred-authentication flag.

gcloud anthos auth login --set-preferred-authentication

You should see a result like the following example, letting you choose a new preferred authentication option:

Your current authentication method is [1] AD Server. Please select your preferred authentication option for cluster [gke-onprem-ldap]
[1] LDAP Server
[2] OIDC
[3] cancel

Please enter your numeric choice:

2

Setting Preferred Authentication option to [OIDC]

Use SSH to authenticate from a remote machine

Suppose you want to SSH into a remote machine and authenticate to a cluster from the remote machine. To do this, your authentication configuration file must be on the remote machine, and you must be able to reach your Open ID provider from your local machine.

On your local machine, run the following command:

ssh [USER_NAME]@[REMOTE_MACHINE] -L [LOCAL_PORT]:localhost:[REMOTE_PORT]

where:

  • [USER_NAME] and [REMOTE_MACHINE] are the standard values used to log in with SSH.

  • [LOCAL_PORT] is an open port of your choice on your local machine that you will use to access the remote machine.

  • [REMOTE_PORT] is the port you configured for your OIDC redirect URL. You can find this in the kubectlRedirectURI field of your authentication configuration file.

In your SSH shell, run the following command to initiate authentication:

gcloud anthos auth login --login-config [AUTH_CONFIG_FILE]

where [AUTH_CONFIG_FILE] is the path of your authentication configuration file on the remote machine.

On your local machine, in a browser, go to http://localhost:[LOCAL_PORT]/login and complete the OIDC login flow.

Now the kubeconfig file on your remote machine has the token that you need to access the cluster.

In your SSH shell, verify that you have access to the cluster:

kubectl --kubeconfig [CLUSTER_KUBECONFIG] get nodes

Log in to clusters from the Google Cloud console (OIDC providers only)

Follow the instructions in Work with clusters from the Google Cloud console.