How to register AKS clusters in Argo CD with Azure workload identity
A platform team running several AKS clusters from one Argo CD should register each cluster with a cluster secret that uses execProviderConfig to call argocd-k8s-auth azure (kubelogin), with AAD_LOGIN_METHOD set to workloadidentity. This keeps static credentials out of the cluster secret, because Argo CD obtains short-lived Entra ID tokens through the workload identity already bound to its pods. The controller and server pods need the azure.workload.identity/use: "true" label, their service accounts need the client and tenant IDs annotations, and AZURE_CLIENT_ID must be set in each cluster secret so the right identity is used for each target cluster.
The trade-off is operational. Workload identity removes stored secrets but ties the setup to the management cluster's federation configuration, so the team must confirm that the identity has been granted access on every managed AKS cluster and that the federated credentials match the namespaces and service accounts Argo CD actually runs under. The other AAD_LOGIN_METHOD options listed in the Argo CD declarative setup guide include spn for a service principal and msi for managed identity, along with devicecode, ropc and azurecli. A service principal needs a client secret or certificate that someone must rotate, so treat it as a fallback where workload identity cannot be configured, and document who owns that rotation.
Before rolling this out, confirm three things in your own environment: that the Argo CD version you run supports the workloadidentity login method with your kubelogin build, that Entra ID RBAC on each AKS cluster grants the identity only the verbs Argo CD needs for the namespaces it deploys to, and that you test a registration in a non-production cluster first. Check the exact annotation and label keys against the current Argo CD documentation before scripting them, since mistakes here usually surface as authentication errors at sync time rather than at registration.
What you need before registering an AKS cluster
Registration only works when four pieces agree: the Argo CD install, the Entra ID tenant and identities, the AKS cluster's authorization model, and a network path from Argo CD to the API server. Check each one before you touch the cluster secret, because a failure in any of them looks like a generic authentication error.
Argo CD installation and service accounts
Identify the application controller and API server pods that will call AKS, and confirm which service accounts they run under. Those service accounts are where the workload identity annotations go, so you need to know their exact names in your install. Confirm the Argo CD version you run against the declarative setup guide, since the workload identity steps depend on the version and on how Argo CD was installed. Also confirm that kubelogin is available in the Argo CD image you deploy.
Entra ID tenant and workload identity
Decide which Entra ID tenant holds the identity Argo CD will use, and whether the management cluster on which Argo CD runs has workload identity enabled with a federated credential for the service account. Record the client ID and tenant ID you will annotate onto the service accounts. Check that the tenant ID in the annotation matches the tenant that owns the AKS cluster, because a mismatch produces token errors that are hard to trace.
AKS cluster and Entra ID RBAC
Confirm that the target AKS cluster uses Microsoft Entra ID for cluster authentication and that Azure RBAC or Kubernetes RBAC decides what the Argo CD identity may do. Grant the identity only the roles that match the namespaces and resource kinds its projects deploy to. Ask your Azure administrator whether any policy blocks local accounts or restricts which identities can read cluster credentials, since those policies will stop registration even when the Argo CD configuration is correct.
Network reachability to the API server
Argo CD must reach the AKS API server endpoint over the network path your design allows. If the cluster uses a private endpoint, or sits behind network rules, the controller and server pods need routing and DNS that resolve the private name. Test the path from the pods that will call the API, not from your workstation, because egress rules often differ between the two. Record the API server address you will put in the cluster secret so it matches the endpoint Azure publishes for that cluster.
Supported versions to confirm
Do not assume that a given Argo CD release, kubelogin release and AKS Kubernetes version work together. Confirm the Argo CD version against the declarative setup guide, confirm the kubelogin version and its supported AAD_LOGIN_METHOD values against your Azure documentation, and check the AKS Kubernetes version against the support window you have agreed. Write the versions you tested into your runbook so an upgrade on either side triggers a repeat of the registration check.
Configuring the cluster secret step by step
This sequence gives Argo CD's controller and server a short-lived Entra ID identity, grants that identity access on the AKS cluster, and registers the cluster with a declarative secret that Argo CD can use without a static kubeconfig.
Label the controller and server pods
Add the label azure.workload.identity/use set to "true" to the Argo CD application controller and server pods. The label tells the Azure workload identity webhook to inject a federated token into those pods. Make the change in the Argo CD install manifests or Helm values your team already manages, so it survives upgrades. Confirm it is done by describing a running pod and checking that the label is present and that the pod carries the projected token volume that the webhook adds.
Annotate the service accounts with client and tenant IDs
Annotate the service accounts used by the application controller and server with the client ID and tenant ID of the Entra ID identity that Argo CD will use. Ask your Entra ID administrator for the application or managed identity client ID and the tenant ID, and record where they came from. Check the result by reading the service account annotations and confirming the values match the identity you intend to use, then restart the pods so the webhook picks them up.
Establish the federated credential for the identity
Configure the federated identity credential on the Entra ID application or managed identity so it trusts the Kubernetes service account issuer and the subject of the Argo CD service account. This is the trust link that lets the pod exchange its token for an Azure token. Confirm it by checking that the federated credential lists the correct issuer, namespace and service account name, and that a test token exchange from inside a labeled pod succeeds.
Grant the identity access on the AKS cluster
Assign the identity a role on the target AKS cluster through Entra ID RBAC for Kubernetes authorization, choosing a built-in or custom role that matches the scope Argo CD needs, such as read access for discovery and write access only in namespaces it deploys to. Ask your platform team which roles are available in your Azure tenant and confirm the exact role names in Azure before assigning them. Verify by running a read request against the cluster as that identity and confirming it is allowed while an out-of-scope action is denied.
Write the declarative cluster secret
Create a Kubernetes Secret in the Argo CD namespace with the label argocd.argoproj.io/secret-type set to cluster. Set the server to the AKS API endpoint and, in the config field, define execProviderConfig that runs argocd-k8s-auth with the azure command. Set AAD_LOGIN_METHOD to workloadidentity and set AZURE_CLIENT_ID in the env list to the client ID from the service account. Keep the secret in your GitOps repository only in encrypted or referenced form, following your secrets policy.
Confirm the cluster is registered and reachable
Once the secret is applied, list the clusters through the Argo CD API or the CLI and confirm the AKS cluster appears with a successful connection status. Then check that the application controller can list resources on the cluster, for example by reviewing the cluster status and controller logs for authentication errors. A registered cluster that shows a connection error usually points to the federated credential, the role assignment or the AZURE_CLIENT_ID value, so review those before changing anything else.
Test a sync to a team namespace
Create a test application scoped to a single namespace on the AKS cluster and sync it. A successful sync confirms that the identity can write to that namespace and that the project destination rules match. Record the result and the role assignments used, so auditors and the platform team can trace which identity deployed to which cluster.
Choosing between workload identity and the other AAD_LOGIN_METHOD options
Workload identity (workloadidentity) is the option this topic is built around. The Argo CD controller and server pods obtain Entra ID tokens through their Kubernetes service accounts, so the cluster secret carries identifiers rather than a password that someone must rotate by hand. It fits when the management cluster can run with workload identity enabled and the team wants unattended sync with no long-lived secret in the registration.
- No stored password: the registration references identities, and no client secret needs to be kept in the cluster secret.
- Pod labeling: the controller and server pods carry the
azure.workload.identity/use: "true"label. - Service account annotations: both service accounts are annotated with the client and tenant IDs.
- Client ID in the secret:
AZURE_CLIENT_IDis set in the cluster secret so kubelogin requests the correct identity. - Upfront setup: the federation prerequisites on the management cluster must exist before registration can succeed.
Confirm the exact label, annotation and secret keys in the declarative setup guide for your Argo CD version before you script the registration.
The msi method uses an Azure managed identity attached to the compute that runs the Argo CD management cluster, such as the node or virtual machine identity. Tokens come from the platform, so there is no secret to store in Git or in the cluster. It fits when the management cluster runs on Azure compute that can carry a managed identity and the team accepts that the identity is tied to the host rather than to individual pods.
- Credential: an Azure managed identity bound to the host, with no secret value to store.
- Scope of trust: other workloads on the same host may be able to use the identity, so review which workloads share those nodes.
- Role assignment: the identity needs Entra ID RBAC on each target cluster, granted before the first sync.
- Rotation: Azure issues tokens for the identity, so the Argo CD team has no password rotation task.
- Blast radius: one identity serving several clusters simplifies access reviews but widens the impact of a compromise.
Ask your Azure administrators which compute resources host the management cluster, who else can run on those nodes, and what the identity is allowed to do on each target cluster.
The spn method authenticates as an Entra ID service principal, using a client secret or certificate that Argo CD and kubelogin can read. It is the fallback when workload identity is not available on the management cluster, for example where the federation prerequisites cannot be put in place. It runs unattended, but the credential is long-lived and becomes a secret that must be stored, rotated and audited.
- Credential: a client secret or certificate for the service principal, held in a Kubernetes Secret or an external store.
- Rotation burden: a named owner must track expiry, because an expired credential stops every sync against the cluster.
- Storage: Kubernetes Secrets are stored unencrypted in etcd by default, so encryption at rest and tight RBAC on Secrets are required.
- Least privilege: grant the principal only the Entra ID role that the target cluster needs.
- Attribution: sign-ins are recorded against one shared principal, which makes per-team traceability weaker.
Confirm in the declarative setup guide which credential fields the spn path expects, and record a rotation owner before the registration goes live.
The devicecode, ropc and azurecli methods rely on a person: a browser sign-in through a device code, a username and password, or a session from the Azure CLI on someone's workstation. They suit one-off testing, local experiments or troubleshooting an authentication path. They are unsuitable for the Argo CD controller because it syncs unattended and cannot complete an interactive prompt or keep a personal session alive.
- devicecode: a person must complete a browser sign-in, which no background sync process can do.
- ropc: a password is submitted directly, a pattern that conflicts with the multi-factor controls many organizations require.
- azurecli: the method reuses a personal CLI session, tying sync to one person's login and its expiry.
- Audit trail: actions are attributed to a person, which blurs the history of automated changes.
- Scope of use: keep these methods for test clusters or supervised troubleshooting, and remove them from production cluster secrets.
Check the value names in the declarative setup guide and confirm with your identity team that no production registration uses an interactive method.
Mapping Azure identities, service accounts and cluster secret fields
This table pairs each Azure object in an AKS registration with the Kubernetes or Argo CD field that carries it, along with who owns the value and where it is recorded. Read it as a checklist: every row should have a named owner and a version-controlled record before the cluster secret is applied.
| Azure or Argo CD object | Where it appears | Owner | Where it is recorded |
|---|---|---|---|
| Managed or workload identity client ID | AZURE_CLIENT_ID in the cluster secret, and the client ID annotation on service accounts | Azure platform team | Azure portal or IaC state, copied into the cluster secret template |
| Entra ID tenant ID | Tenant ID annotation on the controller and server service accounts | Azure platform team | Entra ID tenant record and the service account manifests in Git |
| Argo CD application controller service account | Annotated for workload identity and labeled on the controller pod | Platform engineering | Argo CD install manifests or Helm values in the platform repository |
| Argo CD API server service account | Annotated for workload identity and labeled on the server pod | Platform engineering | Argo CD install manifests or Helm values in the platform repository |
| AAD_LOGIN_METHOD value | execProviderConfig args in the cluster secret, such as workloadidentity or spn | Platform engineering, confirmed with the security team | Cluster secret manifest in Git, with the choice recorded in the design decision log |
| Entra ID group or role with cluster access | Azure role assignments on the AKS cluster, and Kubernetes RBAC bindings to that group | Cloud identity administrators | Entra ID group membership and AKS role assignments, exported in change records |
| Argo CD project and SSO role | AppProject roles bound to the SSO group that deploys to the cluster | Platform team with application owners | AppProject manifests and the Argo CD RBAC configuration in Git |
| Cluster secret name and server URL | Secret metadata and the server field identifying the AKS API endpoint | Platform engineering | Declarative cluster secret in Git, with the label that marks it as a cluster |
Controls that keep the AKS integration least privilege
Registering an AKS cluster gives Argo CD a path into that cluster's API, so the controls around it matter as much as the login method. The cards below cover what the Argo CD identity may do, where cluster credentials live, who can read them, and what the repo-server can run. Each one is a decision you can check in your own environment before the registration goes live.
Scope the Argo CD identity per destination
Bind the identity that Argo CD uses on each AKS cluster to only the Kubernetes permissions that cluster's applications need. Entra ID group or role assignments on the cluster should match the namespaces and resource kinds each AppProject allows, not a broad cluster-admin grant. Check that every destination has its own binding and that the binding can be reviewed and removed without touching other clusters.
Keep cluster secrets declarative
The AKS cluster secret holds the execProviderConfig, the AAD_LOGIN_METHOD value and the AZURE_CLIENT_ID, so it is configuration you want reviewed and versioned. Store it as a labeled Kubernetes Secret, and keep any real identifiers that must stay private out of plain Git through your secret tooling of choice. Confirm who can create or edit these Secrets and whether changes pass through a review step.
Restrict who can read Secrets
Cluster registrations are Kubernetes Secrets in the Argo CD namespace, so anyone who can list or watch Secrets there can read the registration data. Kubernetes stores Secrets unencrypted in etcd by default, so confirm that encryption at rest is enabled on the management cluster. Limit list and watch access to the platform team with least-privilege RBAC, and audit who holds those verbs on the namespace.
Treat the repo-server as a code execution point
The repo-server runs Helm and Kustomize on repository content to render manifests, so a malicious chart or a Kustomize overlay that reads files outside its tree can reach what the repo-server can reach. Limit which repositories each project may use, avoid pulling untrusted charts, and review plugins before enabling them. Ask who approves a new repository source and whether the repo-server has network paths beyond Git and registries.
Confirm credential redaction in outputs
Argo CD redacts cluster, Git and OAuth2 credentials from API responses and logs, which lowers the chance that a registration leaks through a dashboard view or a log export. Redaction does not replace access control, so the Secrets themselves still need restricted reads. Test redaction in your own installation by viewing the cluster in the UI and API and searching controller and server logs after a registration.
How to test the registration before teams depend on it
Test the AKS registration on a non-production cluster before any team deploys to it. Register the cluster with the same cluster secret you intend to use in production, including the execProviderConfig that calls argocd-k8s-auth with the AAD_LOGIN_METHOD you chose and the AZURE_CLIENT_ID value. Then sync a small test application built from a manifest whose contents you know in advance, such as a single ConfigMap with a fixed name and label. A successful sync shows that the controller can obtain a token, reach the API server and create objects. Confirm the result in both the Argo CD UI and with kubectl against the cluster, because a green sync status in Argo CD alone does not prove the Entra ID group mapping on the cluster grants what you expect.
Next, check the boundaries. Create the test application in an AppProject that lists only the test cluster and one namespace as destinations, then try to deploy into a different namespace and confirm Argo CD refuses it. Add a resource kind to the test manifest that the project's cluster resource allow list excludes, such as a ClusterRole, and confirm the sync is blocked with a permission error. Also confirm that the Entra ID role assignments on the cluster match your intent by attempting the same writes with the Azure identity directly. If a check passes only because the project is permissive, fix the project before you rely on this registration.
Finally, test failure and token refresh. Azure role assignments and identity changes take effect outside Argo CD, and the kubelogin token is refreshed on use, so a revoked role may not stop syncs immediately. Remove the test role assignment or rotate the credential the registration depends on, then trigger a sync and record how long it takes to fail and what the error says. Repeat the test after a controller or repo-server restart. Confirm with your Azure and cluster administrators how their change process propagates role changes, and document the expected failure mode so on-call engineers can tell an identity problem from a Git or manifest problem.
Common failures when Argo CD cannot reach an AKS cluster
This table lists the failures teams hit most often when Argo CD cannot read or sync an AKS cluster registered with workload identity, with the likely cause and a check to run for each. Work down the rows in order, because later checks depend on the identity wiring being right. Most failures trace back to a label, annotation, client ID or login method that does not match the identity type.
| Symptom | Likely cause | Check and fix |
|---|---|---|
| Controller or server pods do not receive Azure credentials | Pods are missing the workload identity label | Confirm the argocd-application-controller and argocd-server pods carry azure.workload.identity/use set to "true". Add the label to the pod template and restart the workloads. |
| Token requests fail with an identity or tenant error | Service account annotations hold the wrong client or tenant ID | Compare the client ID and tenant ID annotations on each Argo CD service account with the managed identity's values in Entra ID. Correct the annotations, then restart the pods so the projected token is refreshed. |
| Cluster appears in Argo CD but authentication to it fails | AZURE_CLIENT_ID is absent or wrong in the cluster secret | Open the cluster secret's execProviderConfig and confirm AZURE_CLIENT_ID is present and matches the identity used for the cluster. Check the secret is in the Argo CD namespace with the cluster label. |
| Login method error from kubelogin in controller logs | AAD_LOGIN_METHOD does not match the identity type | Set AAD_LOGIN_METHOD to workloadidentity for workload identity. Use msi, spn or other values only when the cluster is registered with that identity type. Confirm the value in the execProviderConfig matches the identity you created. |
| 403 Forbidden from the API server after authentication succeeds | No Entra ID RBAC binding on the cluster for the identity | Check that the managed identity has a role assignment on the AKS cluster for the access level Argo CD needs. Confirm the cluster's Entra ID integration is enabled and the identity's object ID is bound through Azure RBAC or a Kubernetes RoleBinding. |
| Connection timeouts or dial errors to the cluster endpoint | Network path to the API server is blocked | From a pod in the Argo CD namespace, test connectivity to the API server endpoint on port 443. Check private cluster settings, network security rules, firewall egress and any authorized IP ranges on the AKS cluster. |
| Controller syncs the cluster but the UI shows it as unavailable | Server pods lack the same identity wiring as the controller | Verify the argocd-server pods have the same label and service account annotations as the controller. Review argocd-server logs for kubelogin errors, since the UI reads cluster state through its own identity path. |
| Cluster works for one pod restart, then fails later | Token or identity configuration applied only to one workload | Confirm the label and annotations are set in the workload manifests, not only patched at runtime. Re-run the checks after a rollout to confirm the configuration persists. |
Questions teams ask before registering AKS clusters
How much effort does registering an AKS cluster in Argo CD take?
The effort depends mostly on how many clusters you register, which identity model you choose and how much RBAC design you need before go-live. One cluster with a single managed identity and a simple project model is a small change. Many clusters, separate Entra ID groups per team and a tested rollback path add work at each step. Effort also grows with the network path, since the Argo CD controller and server must reach each API server. Ask for the scope to list cluster count, identity method, RBAC mapping and network checks as separate line items so you can see what each one adds.
What does the work need from our team before it starts?
You need people who can make changes in both Azure and Kubernetes. That means Azure access to create or assign identities, Entra ID administrators who own group membership and role assignments on the AKS clusters, and Kubernetes administrators who can edit the Argo CD namespace, service accounts and cluster secrets. A non-production AKS cluster is strongly advisable for testing the workload identity setup before production. Confirm these owners and the change windows in writing at the start, because delays usually come from waiting on identity approvals rather than from the technical steps.
Can our internal platform team do this without a partner?
Yes, if the team already runs Argo CD and AKS and has people who understand Entra ID. The core steps are documented in the Argo CD declarative setup guide: labeling the controller and server pods, annotating their service accounts with client and tenant IDs, and setting the cluster secret with the right login method. The harder parts are usually organizational: agreeing on identity boundaries, mapping Entra ID groups to Argo CD roles and proving that a failed token refresh does not leave deployments stuck. A partner is useful when the internal team lacks time or experience with those areas.
How long does a fixed-scope engagement usually take?
DeployOpen agrees scope, deliverables and timelines in writing before work starts, so the duration comes from the written scope rather than a standard figure. Ask for the timeline to be tied to the number of clusters, the identity model, the test cluster availability and the approvals you need from Entra ID owners. Ask which milestones depend on your teams, such as group creation or change approval, so a delay on your side is visible in the plan.
Which identity method should we choose for AKS workload identity?
Workload identity suits teams that want Argo CD to authenticate to each AKS cluster without long-lived service principal secrets. The alternatives in the kubelogin options are service principal, managed identity, Azure CLI and device code, each with different operational trade-offs. Service principal credentials are a fallback when workload identity cannot be used, and they need a rotation process. Decide this with your identity owners, because it affects who can revoke access and how audits trace a deployment back to an identity.
What recurs after the integration is live?
Several things recur. Argo CD releases a minor version four times a year and supports only the three most recent minor versions with patch releases, so the Argo CD version and the kubelogin binary inside it need regular upgrades. Kubernetes minor versions also leave support on a fixed schedule, and clusters must be upgraded before their version falls out of support. Identity changes, such as renamed groups, rotated credentials or changed tenant policies, can break access silently. Ask for a plan that names who owns each of these recurring tasks and how they are tested.
Which Kubernetes RBAC and Entra ID checks should we verify on each cluster?
Verify that each Entra ID group maps to a specific Kubernetes role on the AKS cluster and that the Argo CD identity holds only the permissions it needs to manage the destinations in its project. Test a sync from a permitted project and a denied sync from another, and confirm the audit trail shows the expected identity. Also check that secrets are not readable by users who do not need them, since Kubernetes stores Secrets unencrypted in etcd by default unless encryption at rest is configured. Ask for these checks as written acceptance criteria.
How Argo CD and Kubernetes upgrades affect AKS registrations
Argo CD ships a minor release four times a year, and only the three most recent minor versions receive patch releases. An Argo CD line that falls out of that window stops getting fixes for the components that handle your AKS registration, so confirm which line you run before each change window. The October 12, 2026 patch releases on the GitHub releases page were v3.5.5 (marked latest), v3.4.11 and v3.3.16, with v3.6.0 in release candidate. Each minor upgrade is also a trigger to retest the cluster secret, its execProviderConfig block that runs argocd-k8s-auth with kubelogin, and the AAD_LOGIN_METHOD value. Retest the Azure login path after every minor upgrade. Record which login method each cluster secret uses so the retest covers each one.
Argo CD 3.0 changed two RBAC behaviors that affect registered AKS clusters. Update and delete permissions now apply only to the application itself, so a team role that relied on them for child resources will stop working after the move. Reading logs now requires an explicit logs, get permission. These changes sit in Argo CD's authorization layer, so they change what an authenticated identity may do inside Argo CD rather than how kubelogin obtains a token. Before upgrading from 2.14, review each project role in your policy.csv, then sync an application and read its logs as a test user in each team's project. The upgrade notes list the full set of changes, and you should work through them before the change window opens.
The AKS control plane version also sets a support window that Argo CD cannot extend. The Kubernetes project maintains the three most recent minor releases, and as of September 2026 those were 1.37 (end of life October 28, 2027), 1.36 (June 28, 2027) and 1.35 (February 28, 2027). Check which of these your AKS clusters run and schedule the next move before one drops out of support. The version skew policy requires kube-apiserver to move one minor version at a time and allows kubelets up to three minor versions older, so sequence Argo CD upgrades and cluster upgrades as separate changes, each followed by a login test. Confirm AKS-specific support dates and upgrade options in Azure's own documentation, because managed service windows can differ from upstream.
How DeployOpen scopes and delivers the AKS registration
DeployOpen plans and implements the Argo CD side of AKS registration inside your own Azure subscriptions and Argo CD installation. Each engagement starts from a written scope that names the clusters, identities, Entra ID groups and verification steps involved.
How we scope
- Inventory the AKS clusters, their Entra ID tenants and which Argo CD instance will manage each one
- Decide with you between workload identity, managed identity and service principal fallback, and record the AAD_LOGIN_METHOD value per cluster
- Agree in writing which Entra ID RBAC roles, Argo CD projects and service accounts are in and out of scope
How we build
- Apply the azure.workload.identity/use label and service account annotations to the Argo CD controller and server pods
- Declare each cluster secret with its execProviderConfig and AZURE_CLIENT_ID, keeping the definitions in version-controlled manifests
- Test cluster sync, token refresh and denied access in a non-production cluster before any production registration
How we hand over
- Deliver the manifests, identity mapping, Entra ID role assignments and a record of every registration decision
- Document the verification steps your team can repeat after cluster upgrades, identity changes or Argo CD upgrades
- Walk your platform and security engineers through the runbook and the evidence produced during testing
How we support
- Engagements are fixed-scope, and the written scope sets the deliverables and timelines before work starts
- Ongoing support, upgrades and continuous testing for the registration are available as a retainer
- Ask any partner for a quote built from the written scope, including what recurs after handover
