Connect Agent overview

When you register a cluster outside Google Cloud to your fleet, Google Cloud uses a Deployment called the Connect Agent to establish a connection between the cluster and your Google Cloud project, and to handle Kubernetes requests. The Connect Agent is not required to establish a connection for GKE clusters running in Google Cloud.

This enables access to cluster and to workload management features in Google Cloud, including a unified user interface, Google Cloud console, to interact with your cluster.

If your network is configured to allow outbound requests, you can configure the Connect Agent to traverse NATs, egress proxies, and firewalls to establish a long-lived, encrypted connection between your cluster's Kubernetes API server and your Google Cloud project. Once this connection is enabled, you can use your own credentials to log back into your clusters and access details about their Kubernetes resources. This effectively replicates the UI experience that is otherwise only available to GKE clusters.

After the connection is established, the Connect Agent software can exchange account credentials, technical details, and metadata about connected infrastructure and workloads necessary to manage them with Google Cloud, including the details of resources, applications, and hardware.

This cluster service data is associated with your Google Cloud project and account. Google uses this data to maintain a control plane between your cluster and Google Cloud, to provide you with any Google Cloud services and features you request, including facilitating support, billing, providing updates, and to measure and improve the reliability, quality, capacity, and functionality of Connect and Google Cloud services available through Connect.

You remain in control of what data is sent through Connect: your Kubernetes API server performs authentication, authorization, and audit logging on all requests via Connect. Google and users can access data or APIs via Connect after they have been authorized by the cluster administrator (for example, via RBAC); the cluster administrator can revoke that authorization.

Connect IAM roles

Identity and Access Management (IAM) allows users, groups, and service accounts to access Google Cloud APIs and to perform tasks within Google Cloud products.

You need to provide specific IAM roles to launch the Connect Agent and interact with your cluster using the Google Cloud console or Google Cloud CLI. These roles do not allow direct access to connected clusters. You can learn more about logging in to clusters from the Google Cloud console in Working with clusters from the Google Cloud console.

Some of these roles allow you to access information about clusters, including:

  • Cluster names
  • Public keys
  • IP addresses
  • Identity providers
  • Kubernetes versions
  • Cluster size
  • Other cluster metadata

Connect uses the following IAM roles:

Role name Role title Description Permissions
roles/gkehub.editor Hub Editor Provides edit access to GKE Hub resources.

Permissions for Google Cloud

  • resourcemanager.projects.get
  • resourcemanager.projects.list

Permissions for Hub

  • gkehub.memberships.list
  • gkehub.memberships.get
  • gkehub.memberships.create
  • gkehub.memberships.update
  • gkehub.memberships.delete
  • gkehub.memberships.generateConnectManifest
  • gkehub.memberships.getIamPolicy
  • gkehub.locations.list
  • gkehub.locations.get
  • gkehub.operations.list
  • gkehub.operations.get
  • gkehub.operations.cancel
  • gkehub.features.list
  • gkehub.features.get
  • gkehub.features.create
  • gkehub.features.update
  • gkehub.features.delete
  • gkehub.features.getIamPolicy
  • gkehub.fleet.*
roles/gkehub.viewer Hub Viewer Provide read-only access to Hub and related resources.

Permissions for Google Cloud

  • resourcemanager.projects.get
  • resourcemanager.projects.list

Permissions for Hub

  • gkehub.memberships.list
  • gkehub.memberships.get
  • gkehub.memberships.generateConnectManifest
  • gkehub.memberships.getIamPolicy
  • gkehub.locations.list
  • gkehub.locations.get
  • gkehub.operations.list
  • gkehub.operations.get
  • gkehub.features.list
  • gkehub.features.get
  • gkehub.features.getIamPolicy
roles/gkehub.connect GKE Connect Agent Provides ability to establish new connections between external clusters and Google. gkehub.endpoints.connect

Resource usage and requirements

Typically the Connect agent installed at registration uses 500m of CPU and 200Mi of memory. However, this usage can vary depending on the number of requests being made to the agent per second, and the size of those requests. These can be affected by a number of factors, including the size of the cluster, the number of users accessing the cluster via the Google Cloud console (the more users and/or workloads, the more requests), and the number of fleet-enabled features on the cluster.