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:
- The latest version of the Google Cloud CLI, the command line tool for interacting with Google Cloud.
kubectl
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:
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME
Replace 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 Connect gateway.
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.
To fetch the cluster credential used to interact with the Connect gateway using a service account, run the following commands:
gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME
Replace SA_EMAIL_ADDRESS
with the email address of the
service account. You can find out more about letting users impersonate a service
account in Manage access to service accounts.
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:
attach
cp
exec
port-forward
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 the command
kubectl get ns
fails. There are multiple potential reasons for this error. Run yourkubectl
commands in verbose mode to see more details, for examplekubectl 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 (clusters outside Google Cloud only). To resolve this issue, you need to verify if
gke-connect
namespace exists on the cluster. If thegke-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 gatewaykubeconfig
. Don't manually edit thekubeconfig
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
orroles/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-rungcloud 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. Earlier 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 earlier 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?
- See an example of how to use the Connect gateway as part of your DevOps automation in our Integrating with Cloud Build tutorial.