Registering GKE clusters in Argo CD with Workload Identity: what the integration does
A platform team running several Google Kubernetes Engine clusters from one Argo CD usually wants to avoid storing long-lived kubeconfig credentials for each cluster. The supported approach is a cluster secret that sets execProviderConfig with the argocd-k8s-auth binary and args set to ["gcp"]. Instead of holding a static token, Argo CD runs argocd-k8s-auth each time it needs to reach the target cluster, and that helper obtains a Google credential for the identity Argo CD is running as. The integration is open source under the Apache-2.0 license, and the Argo CD declarative setup guide describes the cluster secret format.
The credential comes from Workload Identity on the management cluster, not from a key file. The application controller and the API server run as their own Kubernetes service accounts, and each is bound to a Google Cloud service account. That Google service account needs an IAM role on each target GKE cluster that allows it to authenticate and receive the access it needs for the namespaces Argo CD will manage. Because the binding is on the service accounts that actually run the controller and server, the trust chain is visible in your IAM and Kubernetes RBAC configuration, and you can review it like any other workload identity.
Before you build this, confirm three things: which Kubernetes service accounts the controller and server use in your install, which Google service account each one will be bound to, and which IAM role that Google service account will hold on each target cluster. Check the exact role names and binding steps against Google's current Workload Identity documentation and the declarative setup guide, since they are the authoritative sources for your version. Keeping the Google service account scoped to the clusters and namespaces each team needs is the main control you own in this design.
What you need before registering a GKE cluster
Registering a GKE cluster touches four systems: the management cluster, Google Cloud IAM, the target cluster's control plane and the Argo CD version you run. Confirm each one before writing any cluster secret, because a gap in any of them usually shows up as an authentication failure that looks like a配置 problem in Argo CD.
Management cluster with Workload Identity
Argo CD runs on a management cluster that must have Workload Identity enabled, so its Kubernetes service accounts can act as Google Cloud identities without a exported key file. Confirm that the cluster and the node pool that hosts Argo CD are configured for Workload Identity, and that you can annotate the service accounts used by the application controller and the server. Without this, the exec provider has no Google credential to exchange.
Target GKE clusters inventory
List every GKE cluster Argo CD will manage, with its Google Cloud project, location and whether it uses a private control plane endpoint. Each registration is a separate Secret, so the list drives how many bindings and IAM grants you create. Record the cluster name exactly as Argo CD will show it, since that name becomes part of the registration and of your project destination rules.
GCP project and service account
Decide which Google Cloud project holds the service account Argo CD will impersonate and which role it receives on each target cluster. Confirm the exact IAM role names for read access to Kubernetes resources with the official Argo CD guide and the Google Kubernetes Engine documentation, rather than assuming them. Ask whether the service account lives in the management project or in each cluster's project, because that choice changes the IAM bindings you maintain.
Network path to each control plane
Argo CD must reach each cluster's Kubernetes API endpoint over the network, which may be a public endpoint, an authorized-networks allow list or a private endpoint reached through VPC peering or a VPN. Check egress from the management cluster to every control plane address on the HTTPS port, and confirm that any authorized networks list includes the management cluster's egress path. A reachability failure surfaces as a timeout during sync, so test it before registration.
Argo CD and argocd-k8s-auth versions
Confirm which Argo CD minor release line you run and whether it is still in the patch window. The release process supports only the three most recent minor versions with patch releases, so an older install will not receive fixes. Check that the argocd-k8s-auth binary available in your Argo CD image supports the gcp argument, and confirm the exact version against the official guide before you pin it.
How to register a GKE cluster step by step
The sequence connects Argo CD to one or more Google Kubernetes Engine clusters without static kubeconfigs, so the controller and server obtain short-lived Google credentials through Workload Identity. Each step ends with a check you can run before moving on.
Enable Workload Identity on the management cluster
The platform team enables Workload Identity on the GKE cluster that runs Argo CD, which lets Kubernetes service accounts act as Google service accounts. Confirm the feature on the cluster and the workload identity pool that GKE assigns to it. Then check that a test pod with the metadata server reachable can request a token for the identity you plan to bind. If the cluster was created without the feature, confirm with your GKE administrator whether it can be enabled on the existing cluster or whether a new management cluster is needed.
Create the GCP service account and grant cluster access
Create a dedicated Google service account for Argo CD, separate from any application identity, and grant it an IAM role on each target GKE cluster that lets it read the cluster and its API. Choose the narrowest role that supports your sync design, and confirm the exact role with Google's current documentation for GKE. Verify the grant by listing the service account's IAM bindings on the target project and confirming the role appears on the intended cluster scope.
Bind the Argo CD Kubernetes service accounts
Bind the application controller and the API server Kubernetes service accounts in the Argo CD namespace to the Google service account, using the Workload Identity member format and the iam.gke.io/gcp-service-account annotation on each Kubernetes service account. Restart the controller and server pods so they pick up the projected token. Confirm the binding by running a command inside the controller pod that prints the identity Google returns, and check that it matches the Google service account you created.
Authorize the Google identity inside each target cluster
Inside each target cluster, grant the Google service account Kubernetes permissions that match the scope Argo CD needs, usually through a Kubernetes RBAC binding to the Google identity's principal. Start with the smallest set of cluster roles that your projects require, and record which namespaces the identity can write to. Confirm the grant with a kubectl auth check run as that identity, such as checking whether it can list namespaces or create deployments in a target namespace, and expect a denial for anything outside the scope you set.
Declare the cluster secret with execProviderConfig
Create a Kubernetes Secret in the Argo CD namespace with the label argocd.argoproj.io/secret-type set to cluster. Set the server field to the GKE cluster API endpoint and the config field to a JSON document whose execProviderConfig points to the argocd-k8s-auth command with args set to ["gcp"]. Include the cluster CA data that the API server uses. Apply the Secret through your Git-managed workflow, not by hand. Confirm the registration by running argocd cluster list and checking that the new cluster shows a successful connection status.
Verify the connection with a test application
Deploy a small, non-production test application from an approved repository into a namespace on the new cluster, scoped to a project that allows only that destination. Watch the sync result in the Argo CD UI or with argocd app get. A healthy result shows the application syncing and the resource reaching the expected health status. Then remove the test application. If the sync fails with an authentication error, check the controller logs for token exchange messages and confirm the Kubernetes service account binding first.
How GCP identities map to Argo CD and cluster roles
The application controller reconciles Applications and connects to each registered cluster to compare live state with Git and apply changes. It is the main consumer of cluster credentials, so its Kubernetes service account needs a Workload Identity binding to the GCP service account. The declarative setup guide describes the cluster secret that points Argo CD at the GKE cluster.
- Who calls the cluster. The controller reads live resources and applies manifests on every destination, so it needs a token that GKE accepts.
- Binding subject. The IAM member is the controller's Kubernetes service account, written in the workload identity pool format for your project.
- Service account annotation. The Kubernetes service account carries the GCP service account email that Workload Identity maps to.
- Replica and shard layout. If you run several controller replicas or shards, confirm which service account each pod uses before adding bindings.
Confirm that the namespace and name of the service account in your install manifests match the binding exactly before you test a sync.
The Argo CD API server handles UI and CLI requests and reads live resource data so it can display application state. That means it also reaches the registered clusters, so its Kubernetes service account needs its own Workload Identity binding. The binding is separate from the controller's even when both point to the same GCP service account, because each Kubernetes service account is a distinct subject.
- Display path. Views of live resources, pod logs and resource trees depend on the server being able to read from the cluster.
- Separate subject. Add one IAM member for the server's Kubernetes service account alongside the controller's member.
- Matching annotation. The server service account carries the same GCP service account email annotation as the controller.
- Symptoms of a missing binding. Applications may sync while the UI shows resource errors or empty live views, so check server logs when that happens.
After the binding is in place, open an Application in the UI on a GKE destination and confirm the live resource tree loads.
One GCP service account can serve both bindings because Workload Identity lets several Kubernetes service accounts be granted the same IAM role. The IAM policy on the GCP service account lists both members, and each member can impersonate that identity. What limits access is the set of IAM roles granted to the GCP service account and the Kubernetes RBAC on each cluster, not the number of Kubernetes service accounts that share it.
- Multiple members. The GCP service account's IAM policy can list the controller and server members together.
- Scope comes from grants. Permissions follow the roles on the GCP service account and the cluster bindings, so sharing the identity does not widen them.
- Shared audit trail. Cloud audit logs show one GCP identity for both components, which can make attribution harder.
- Separate identities as an option. Two GCP service accounts let you grant the server less than the controller, at the cost of managing two sets of roles and bindings.
- Impersonation rights. Limit who can impersonate the GCP service account to the Argo CD members and the administrators who maintain them.
Decide before rollout whether one shared identity meets your audit and separation requirements, and record that decision with the cluster inventory.
Authentication and authorization happen in two places. The argocd-k8s-auth plugin, configured with the gcp argument in the cluster secret's execProviderConfig, obtains a token for the GCP identity. GCP IAM determines whether that identity can reach the cluster and retrieve credentials. Inside the target cluster, Kubernetes RBAC decides which namespaces and verbs the identity can use, so the GCP role alone does not define what Argo CD can change.
- Token first. The plugin exchanges the workload identity for a credential that the GKE API server accepts.
- Project role decides reach. The GCP role determines whether the identity can access the cluster and fetch its endpoint.
- Cluster bindings decide actions. RoleBindings or ClusterRoleBindings for the identity set what it can read or write.
- Start narrow. Grant namespace-scoped access first, then widen only for features your install mode requires. Confirm the minimal GCP role in Google Cloud documentation for your environment.
- Record each destination. Keep a register of which bindings apply to each registered cluster.
Test with a sync to a non-production namespace and read the Kubernetes denial messages to confirm each permission is needed.
Which Kubernetes and GCP objects map to which Argo CD settings
This table traces each object in a GKE registration, from the cluster Secret Argo CD reads to the GCP service account and in-cluster RBAC it depends on. Read it top to bottom to see where each setting lives and which team usually owns it. The main takeaway is that the cluster Secret only tells Argo CD how to get a token, while IAM and Kubernetes RBAC decide what that token can do.
| Object | Where it lives | What it controls | Who owns it |
|---|---|---|---|
| Cluster Secret (name, server) | Argo CD namespace on the management cluster, labeled as a cluster Secret | Destination name and API server URL Argo CD uses when an Application targets this GKE cluster | Platform team, usually in Git |
| Cluster Secret (config.execProviderConfig) | Same Secret, under the config field | Command argocd-k8s-auth with args gcp, so Argo CD fetches a short-lived token instead of a stored credential | Platform team |
| Kubernetes service accounts for the controller and server | Management cluster, Argo CD namespace | The identities Argo CD pods run as, which Workload Identity maps to a GCP service account | Platform team |
| Workload Identity binding | GCP IAM policy on the GCP service account | Lets the Kubernetes service accounts for the controller and server act as the GCP service account | Cloud or platform team with IAM admin rights |
| GCP service account and IAM role | Target project in Google Cloud | The Google identity Argo CD uses to request credentials for the GKE cluster, bounded by the role granted | Cloud team, reviewed by security |
| Cluster-level IAM role on the GKE cluster | Target project, bound to the GCP service account | Whether the service account can read the cluster through the Kubernetes API, which role is needed is a point to confirm in the Argo CD setup guide | Cloud team |
| In-cluster authorization entry | Target GKE cluster, inside Kubernetes RBAC | The Kubernetes permissions the mapped Google identity holds once authenticated, which bound what Argo CD can deploy | Cluster owner or platform team |
| Argo CD AppProject destination | Management cluster, AppProject resource | Which clusters and namespaces a team's Applications may target, independent of the cluster Secret itself | Platform team, with team leads consulted |
Security controls for GKE cluster registrations
Each GKE registration gives Argo CD a path into a production cluster, so the controls sit at four points: the Google identity Argo CD assumes, the Kubernetes secrets that hold the registration, the API traffic, and the repositories allowed to deploy. Work through them in that order before the first cluster is added.
Least-privilege IAM on the service account
Grant the GCP service account only the IAM role needed to get credentials for the clusters it manages, and bind that role at the project or cluster level you actually intend. Avoid broad editor or owner roles, because anything the service account can do in Google Cloud becomes reachable from Argo CD. Confirm the exact role and its scope with your GCP administrator and the current GKE documentation before you bind it.
Limiting which clusters each identity reaches
Use separate GCP service accounts for clusters that belong to different trust zones, such as production and non-production, so one compromised identity cannot reach every cluster. Pair each identity with its own cluster registration and a project that lists only that cluster as a destination. Ask your platform team to map each identity to the clusters it may touch and review that map whenever a cluster is added.
Keeping cluster secrets out of Git
The cluster registration is a Kubernetes Secret that holds the cluster endpoint and the auth configuration. Store it through a secrets workflow such as sealed secrets or an external secret store rather than committing the manifest in plain text. Keep the label that marks it as a cluster secret, so Argo CD recognizes it, and confirm your review process covers changes to these files.
Restricting Secret read access in the Argo CD namespace
Anyone who can read Secrets in the Argo CD namespace can read every cluster registration and repository credential stored there. Limit list and watch access on Secrets to the platform team and to the Argo CD components that need them. Confirm, with kubectl auth can-i checks run as each application team, that tenants cannot read the registration secrets even when they hold Argo CD roles.
TLS to cluster API endpoints
Argo CD reaches each GKE control plane over its API endpoint, so the registration must carry the correct CA data and the connection must verify the server certificate. Do not disable certificate verification to get a registration working. Check the endpoint and CA values against the cluster details in Google Cloud whenever a cluster is rebuilt or its endpoint changes.
Repositories decide what gets deployed
The repo-server runs Helm and Kustomize on repository content, and the security documentation flags untrusted repositories and out-of-tree file access as a risk. A cluster registration is only as safe as the repositories allowed to deploy to it, so set each project's source repositories to an explicit list. Review changes to that list with the same care as changes to the registration itself.
Why a GKE cluster shows Unknown or Failed in Argo CD
This table lists the failures that most often leave a registered GKE cluster showing Unknown or Failed in Argo CD, with the likely cause and fix for each. Work down the rows in order, because a missing Workload Identity binding or wrong service account name blocks every check that follows it. Confirm each item in your own project and cluster before changing the Argo CD cluster secret.
| Symptom | Likely cause | Fix | What to check |
|---|---|---|---|
| Authentication error when Argo CD connects to the cluster | Workload Identity binding is missing between the Google service account and the Kubernetes service account used by the controller or server | Add the roles/iam.workloadIdentityUser binding for the member serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME] on the GCP service account | Run a policy read on the GCP service account and confirm the member string matches the Kubernetes service account exactly |
| Cluster stays Unknown after registration, with no token issued | Wrong Kubernetes service account name or namespace in the Workload Identity member or the Kubernetes annotation | Correct the namespace and name so they match the argocd-application-controller and argocd-server service accounts in your install | Compare kubectl get serviceaccount output in the Argo CD namespace with the binding member string, character by character |
| Permission denied when reading the GKE cluster | IAM role not granted on the project that hosts the target cluster, or granted on a different project | Grant a role with Kubernetes Engine read access on the target project to the GCP service account, following the Argo CD declarative setup guide | Confirm the project ID in the cluster secret and the project that owns the GKE cluster are the same |
| Connection works, but applications fail with Forbidden | Cluster-side authorization is missing, so the mapped identity has no Kubernetes RBAC on the target cluster | Create a ClusterRoleBinding or RoleBinding on the target cluster for the Google identity Argo CD uses, scoped to the namespaces the team needs | Run kubectl auth can-i with the same identity on the target cluster to test each verb Argo CD needs |
| Cluster shows Failed with a dial or TLS error | Server endpoint in the cluster secret does not match the current control plane address, or the cluster is private and unreachable from the management cluster | Update the server field to the current endpoint and confirm network paths from the management cluster to the control plane | Check the endpoint in the GKE console against the cluster secret, and confirm the management cluster network can reach it |
| Error that the argocd-k8s-auth binary cannot be found or executed | argocd-k8s-auth is not present in the image used by the controller or server, or the execProviderConfig command is misspelled | Use an Argo CD image that includes argocd-k8s-auth, or add it to the image through your build, and confirm the command and args are gcp | Inspect the running pods for the binary, and check the cluster secret execProviderConfig command and args fields |
| Cluster works in one Argo CD component but not another | Binding exists for the controller service account but not the server service account, or the reverse | Add the Workload Identity binding for each service account that needs to authenticate to the cluster | List both service accounts and confirm each has its own binding and annotation on the management cluster |
| Credentials appear to work for a time and then fail | Token issued through the Google identity expires or the Workload Identity metadata path is not reachable from the pod | Check the pod has Workload Identity enabled on its node pool or workload, and re-test once the metadata server is reachable | Review controller and server logs for token or metadata errors, and confirm the GKE Workload Identity setting on the management cluster |
How to test the registration and keep it working
Test each binding before you trust the registration. Run kubectl auth can-i against the target cluster while impersonating the Google service account that the Argo CD application controller and server use, and confirm the verbs and namespaces match the access you planned, nothing more. Then run a short-lived test pod under a Kubernetes service account bound to the same Google service account and have it call the cluster API, so you prove the Workload Identity path works from inside a pod rather than only from your laptop. Finally, create a throwaway Application in a non-production namespace, scoped to a project that lists only this cluster, and confirm it reaches Synced and Healthy. A failed sync here often points to a missing IAM role or a binding on the wrong service account, which is cheaper to find now than during a production change.
Recheck the setup after every Argo CD upgrade. The 2.14 to 3.0 upgrade notes changed how update and delete RBAC applies (only to the application itself), require an explicit logs, get permission for log access, and make annotation-based resource tracking the default. Any of these can change what the controller or a team can see or do on a GKE destination, so rerun the test Application and your kubectl auth can-i checks against the new version in staging first. Confirm which exact release your team is on by checking the Argo CD releases page, since patch support covers only the three most recent minor versions.
Recurring work is small but needs an owner. Schedule periodic IAM reviews of the Google service account and its project role, and remove any binding that no longer maps to a registered cluster. Do not plan manual credential rotation: argocd-k8s-auth requests short-lived tokens through Workload Identity, so there is no static key to rotate, but you should confirm that no legacy JSON key was left behind in a cluster secret. Monitor cluster connection status in the Argo CD UI or through its API, and alert on a cluster that turns unreachable, because token or IAM failures often show up there before any application drifts. Ask your GKE platform team which audit logs in your Google Cloud project record calls made by that service account, and confirm they are retained long enough for your review cycle.
Questions teams ask before registering GKE clusters
How much effort does registering a GKE cluster take, and what drives it?
The effort depends mostly on how many clusters you register, how your IAM model is organized, and how much RBAC already exists on each cluster. Each cluster needs a Kubernetes secret that uses execProviderConfig with argocd-k8s-auth and the gcp argument, so the work scales with the cluster count. A single project with one service account and one cluster-admin binding is a small task. Several GCP projects, separate service accounts per environment, and clusters that already have hand-written RBAC need more discovery, testing and sign-off. Ask any partner for a written scope that lists each cluster, each GCP project, the IAM role and binding design, and the RBAC you expect Argo CD to hold on each destination.
Can our in-house platform team register GKE clusters without outside help?
Yes, if the team already runs Kubernetes and Google Cloud and has someone comfortable with Workload Identity. The setup is a set of well-defined steps: enable Workload Identity on the management cluster, create a Google service account with an appropriate IAM role, bind it to the Argo CD application controller and server Kubernetes service accounts, and then declare the cluster secret. The hard parts are less about the commands and more about decisions: which role to grant, how to scope access per team, and how to test that a sync fails when it should. Teams without recent GKE or IAM experience usually benefit from a short design review before they start, and from a written test plan for each registered cluster.
Which people do we need to involve, and what do they have to provide?
Three groups usually need to take part. GCP project owners or IAM administrators must approve the service account, its IAM role and the Workload Identity binding. Cluster administrators on each target GKE cluster must agree to the RBAC that the Argo CD identity receives there. Argo CD administrators must provide the management cluster access, the declarative cluster secrets and the AppProject boundaries that limit what each team can deploy. Before work starts, confirm who signs off on IAM changes, how change tickets are raised, and which environment will be used for testing. A written scope should name each of these roles and the approval step they own.
Do we still need static kubeconfigs or long-lived service account keys?
With this pattern, Argo CD does not need a static kubeconfig stored in its cluster secrets. The argocd-k8s-auth helper obtains short-lived credentials for the Google service account when Argo CD connects, and Workload Identity lets the Argo CD pods act as that service account without a downloaded JSON key. You should still check that no older cluster secrets or exported keys remain, because a leftover kubeconfig can keep a path open that bypasses the new design. Ask for a review of every existing cluster secret, a removal plan for old credentials, and confirmation that the Google service account has no user-managed keys attached.
Does the GKE registration change after an Argo CD upgrade?
It can. Argo CD's upgrade notes for 2.14 to 3.0 changed several behaviors that affect access, including that update and delete RBAC now apply only to the application itself and that logs access needs an explicit logs, get permission. Those changes affect what your RBAC policy must grant, even if the cluster registration itself still works. Each minor upgrade should be checked against the official upgrade notes, and the cluster secrets, Workload Identity bindings and policy file should be retested in a non-production environment first. Ask any partner to include upgrade testing in the written scope, and to say whether that testing is a one-time task or part of an ongoing support arrangement.
What should we ask for in a written scope for this work?
A useful scope lists the Argo CD version and installation method, the number and names of GKE clusters, the GCP projects involved, and the Google service account and IAM role for each. It should describe the Workload Identity bindings for the application controller and server, the form of each cluster secret, and the Kubernetes RBAC granted on each destination. Add verification steps such as a test application that syncs to each cluster, a check that a denied namespace fails, and a list of existing credentials to remove. Finally, ask what is one-time work, what recurs, who maintains the setup after handover, and what the process is for an upgrade. Quotes follow from this written scope, not from a list price.
What are the most common failures when registering GKE clusters?
The most common problems are a missing Workload Identity binding between the Google service account and the Kubernetes service account, an IAM role that is too narrow for the cluster API calls, or an RBAC binding on the target cluster that does not match the identity Argo CD presents. These usually show up as an authentication or forbidden error when the cluster is first tested. A second group of problems comes from leftover secrets, overly broad roles, or a default project that allows any destination. Your team should check each failure mode during testing and keep a record of the bindings and roles so that troubleshooting after an upgrade is faster.
Official sources for the GKE registration method
The primary reference for this method is the Argo CD declarative setup guide, which defines the cluster secret format this page relies on. Use it to confirm the exact fields of a cluster Secret that uses execProviderConfig with argocd-k8s-auth and the argument gcp, including how the config block is encoded and where the server and name values belong. Check the guide against the Argo CD version you run before you write the first Secret, because the declarative settings are the part of the platform most likely to change between minor releases. Treat the guide as the source for what Argo CD expects, and treat your own test cluster as the source for whether it works.
The Kubernetes authentication documentation explains how the cluster API server decides who a caller is, which matters here because the identity Argo CD presents comes from Google rather than from a static kubeconfig. Read it to understand how bearer tokens and OpenID Connect or JWT-based identities are verified, and then confirm with Google Cloud how the GKE control plane maps the Google identity to Kubernetes users and groups for the cluster. Record the mapping you find, including which RBAC subject the service account ends up as, so the access review later does not depend on memory. Where the two documents disagree on a detail, the cluster's own behavior is the answer, and the gap should go into your change record.
How DeployOpen scopes and delivers GKE registrations
DeployOpen plans, builds and documents Argo CD connections to Google Kubernetes Engine clusters inside your own Google Cloud environment. Each engagement starts from a written scope that names the clusters, the Argo CD namespaces and the IAM boundary before any binding is created.
How we scope
- Inventory the GKE clusters, projects and Argo CD controller and server service accounts that need registration
- Define the GCP service account, its IAM role and the Workload Identity bindings in writing before work starts
- Agree which clusters are management and which are destinations, and record that split in the fixed-scope agreement
How we build
- Configure Workload Identity on the management cluster and bind the controller and server Kubernetes service accounts
- Declare each cluster secret with execProviderConfig using argocd-k8s-auth and the gcp argument, kept in version control
- Test that each registration authenticates, lists resources and is denied any action outside its written role
How we hand over
- Deliver a runbook covering each binding, secret, service account and IAM role, with the reason for each
- Walk your platform team through rotating access, adding a cluster and revoking a registration
- Document the verification steps so your team can repeat them after changes or an upgrade
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover
- Ask any quote to separate one-time build effort from recurring support, upgrades and testing
- Review IAM roles and bindings again when Argo CD or your GKE versions change, using the release notes
