Using the Connect gateway

This page tells you how to use the Connect gateway to connect to a registered cluster. Before reading this guide, you should be familiar with the concepts in our overview. The guide assumes that your project administrator has already set up the gateway, and given you the necessary roles and permissions.

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.

Log in to your Google Cloud account

You can use your own Google Cloud account or a Google Cloud service account to interact with connected clusters via the gateway API.

Follow the instructions in Authorizing Google Cloud CLI tools to log in to your user account. The Connect gateway supports service account impersonation, so even if you're logged in to your own user account you can use a service account to interact with clusters, as you'll see in the following sections.

Select a registered cluster

If you don't know the name of the cluster you want to access, you can see all your current fleet's registered clusters by running the following command:

gcloud container fleet memberships list

This lists all your fleet's clusters, including their membership names and external IDs. Each cluster in a fleet has a unique membership name. For GKE clusters, the membership name generally matches the name you gave it when you created the cluster, unless the cluster's name was not unique within its project at registration.

Get the cluster's gateway kubeconfig

Use the following command to get the kubeconfig you need to interact with your specified cluster, replacing MEMBERSHIP_NAME with your cluster's fleet membership name. This command returns a special Connect gateway-specific kubeconfig that lets you connect to the cluster through the gateway.

# Fetch cluster credential used to interact with Connect gateway
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

If you want to use a service account rather than your own Google Cloud account, use gcloud config to set auth/impersonate_service_account to the service account email address. You can find out more about letting users impersonate a service account in Manage access to service accounts.

# Fetch cluster credential used to interact with Connect gateway, using a service account
gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Run commands against the cluster

Once you have the necessary credentials, you can run commands using kubectl or a go-client as you normally would for any Kubernetes cluster. Your output should look something like the following:

# Get namespaces in the Cluster.
kubectl get namespaces
NAME              STATUS   AGE
default           Active   59d
gke-connect       Active   4d

The following kubectl commands are not supported by the gateway:

  • exec
  • proxy
  • port-forward
  • attach

Troubleshooting

If you're having problems connecting to a cluster through the gateway, you or your administrator can check for the following common issues.

  • The server doesn't have a resource type: You may see this error message when a simple command like kubectl get ns fails. There are multiple potential reasons for this error. Run your kubectl commands in verbose mode to see more details, for example kubectl get ns -v 10.
  • Cannot find active connections for cluster(project: 12345, membership: my-cluster): You may see this error when Connect Agent loses connectivity or isn't installed properly. To resolve this issue, you need to verify if gke-connect namespace exists on the cluster. If not, see Registering a cluster with the Google Cloud CLI. If the gke-connect namespace exists on the cluster, see the Connect Troubleshooting page to fix the connectivity issues.
  • The requested URL was not found on this server: You may see this error when the kubeconfig contains an incorrect server address. Make sure the Google Cloud CLI version you're using is the latest version and retry to generate the gateway kubeconfig. Do not manually edit the kubeconfig file, which will cause unexpected errors.
  • The user identity does not have sufficient permissions to use the gateway API: You need the roles/gkehub.gatewayAdmin roles/gkehub.gatewayReader or roles/gkehub.gatewayEditor role to use the API. See Grant IAM roles to users in the gateway setup guide for more details.
  • The Connect agent is not authorized to send the user’s requests: The Connect agent needs to be allowed to forward requests on your behalf, which is specified using an impersonation policy on the cluster. See Configure RBAC authorization in the gateway setup guide for an example of adding a user to the gateway-impersonate role.
  • The user identity does not have sufficient RBAC permissions to perform the operation: You must have appropriate permissions on the cluster to run your chosen operations. See Configure RBAC authorization in the gateway setup guide for an example of adding a user to the appropriate ClusterRole.
  • The user identity does not have sufficient permissions to perform the operation when using Google Groups or third-party support: See Collecting GKE Identity Service logs for instructions on how to inspect logs related to identity information.
  • The Connect agent is unhealthy: See the Connect Troubleshooting page to make sure your cluster is connected.
  • executable gke-gcloud-auth-plugin not found or no Auth Provider found for name gcp: kubectl versions 1.26 and later may display this error due to changes to kubectl authentication starting with GKE v1.26. Install gke-gcloud-auth-plugin and re-run gcloud container fleet memberships get-credentials MEMBERSHIP_NAME with the latest version of Google Cloud CLI.
  • Connections to the gateway fail with older versions of the Google Cloud CLI: For GKE clusters, the Connect agent is no longer required for the gateway to function so it does not get installed by default during membership registration. Older versions of the Google Cloud CLI (399.0.0 and below) assume the existence of the Connect agent on the cluster. Attempting to use the gateway with these older versions may fail on clusters registered with a newer version of the Google Cloud CLI. To resolve this, either upgrade your Google Cloud CLI client to a newer version or re-run the membership registration command with the --install-connect-agent flag.

What's next?