What Argo CD sync impersonation does and when teams need it
Many Argo CD installations deploy to several clusters and namespaces using one control plane account that holds broad rights everywhere. Sync impersonation makes each sync run as a service account chosen for its destination, so a change to a team's namespace on one cluster no longer depends on the same powerful identity that can touch every other destination. The feature is a Beta introduced in v3.5.0 and is disabled by default. Enabling it is a deliberate platform change, and the reader should plan it the way they would plan any change to how credentials are used. The case for least privilege per destination is strongest when destinations differ in sensitivity: a production cluster with regulated workloads, a shared cluster hosting several tenants, or namespaces owned by teams that should not be able to change each other's resources. In those cases, the extra RBAC work is the price of making the boundary enforceable at the Kubernetes layer rather than relying on AppProject settings alone. It is less compelling for a single-tenant cluster where the platform team already owns everything. Before committing, confirm which destinations truly need separate identities, which teams own them, and whether each service account can be scoped with Role and RoleBinding objects that match what each application really deploys. The main cost is operational. Each destination mapping needs a service account, a role that covers the resource kinds and verbs the application uses, and a review process when new kinds are added. Because impersonated accounts also need matching rights for viewing logs, listing events, deleting resources and running resource actions, under-scoped roles show up as failed operations rather than failed syncs. Ask whoever runs the platform to inventory the resource types each application deploys, the verbs each team expects, and the release cadence that will drive RBAC updates.
Configuration options and when each fits
This table compares the four configuration points that control sync impersonation: the global switch, the destination mapping on each AppProject, the enforcement setting and the catch-all entry. Read each row for when the option fits and what it trades off, then check the impersonation guide for the exact keys in your Argo CD version before changing production settings.
| Option | What it controls | When it fits | Trade-off to plan for |
|---|---|---|---|
| application.sync.impersonation.enabled in argocd-cm | Turns sync impersonation on system-wide. Feature is Beta, introduced in v3.5.0, and off by default. | Teams on Argo CD 3.5 or later that want syncs to run under per-destination accounts and can accept Beta behavior. | Until enabled, syncs keep using the control plane account, so no least-privilege gain. Confirm Beta status fits your change policy. |
| AppProject destinationServiceAccounts: server | Matches the destination cluster that an Application syncs to. | Separate clusters with different trust levels, such as production and non-production clusters. | Each cluster needs a mapping. Renamed or re-registered clusters can stop matching until the entry is updated. |
| AppProject destinationServiceAccounts: namespace | Matches the destination namespace within the matched cluster. | Scope a privileged account to the namespaces one team owns, keeping other namespaces on narrower accounts. | Namespace patterns are order sensitive. Broad patterns placed early can shadow narrower ones. |
| AppProject destinationServiceAccounts: defaultServiceAccount | The Kubernetes service account used for syncs that match the entry. | Give each team or environment its own service account with only the RBAC verbs its workloads need. | The account must have RBAC for every server operation in 3.5, including logs, events, deletes and resource actions, so grants need review. |
| Match order (first valid match wins) | Determines which entry applies when several entries match the same destination. | Place specific entries first and the catch-all last so intended mappings are used. | A misordered list can grant a broader account than intended, and the effect is easy to miss in review. |
| application.sync.impersonation.enforced set to true (default behavior per guide) | A sync fails when no destinationServiceAccounts entry matches the destination. | Production and regulated environments where every sync should have an explicit identity. | Any destination without a matching entry blocks deployments. Inventory all destinations before enabling. |
| application.sync.impersonation.enforced set to false | Syncs with no matching entry fall back instead of failing. | Migration periods where some destinations are not yet mapped and blocking would stop work. | Unmapped destinations keep running under the control plane account, which weakens the isolation the feature provides. |
| Catch-all entry with low priority | Matches any remaining server and namespace, placed last in the list. | A safety net that keeps syncs working while stricter entries are rolled out. | A broad account behind the catch-all can become the de facto privileged identity, so keep its RBAC narrow. |
Setting up impersonation step by step
This sequence turns on Argo CD sync impersonation for one installation, gives each destination its own less privileged identity, and confirms that every destination syncs under the account you intended. It produces a tested mapping that you can extend to more clusters and namespaces.
Confirm the Argo CD version and feature status
Check that the Argo CD installation runs v3.5 or later before changing anything. Sync impersonation was introduced in v3.5.0 as a Beta feature, so confirm its current status for your exact version in the impersonation guide and in the release notes, and record the version in your change ticket. Done means the running version is documented and the Beta status is confirmed for that version, including any changes since your release.
Enable the feature flag in argocd-cm
A platform engineer with access to the argocd namespace sets application.sync.impersonation.enabled to true in the argocd-cm ConfigMap. Impersonation is disabled by default, so this is the switch that turns the behavior on system-wide. Verify by reading the ConfigMap back and confirming the key is set, then check that the application controller has restarted or reloaded its configuration, as your installation requires.
Create one service account per destination
For each destination cluster and namespace, create a Kubernetes service account in the target environment and bind it with a Role or ClusterRole that grants only the verbs and resources that application needs. Remember that in Argo CD 3.5 impersonation covers viewing logs, listing events, deleting resources and running resource actions, so include those verbs where operators rely on them. Verify with kubectl auth can-i, impersonating each account, that it can do what it needs and nothing else.
Map destinations in each AppProject
In each AppProject, add entries under .spec.destinationServiceAccounts that pair a destination server and namespace with the defaultServiceAccount to use. Remember that the first valid match wins, so order specific entries before broader ones. Add a low-priority catch-all entry for destinations you have not yet mapped, and decide deliberately whether it points to a restricted account. Verify by viewing the AppProject and confirming each entry matches the intended server and namespace.
Decide how strictly unmatched syncs are handled
Decide whether a sync with no matching destination should fail. By default the sync fails when nothing matches, which is the stricter behavior. Setting application.sync.impersonation.enforced to false lets syncs fall back, which weakens the control, so document the choice for your auditors. Verify by creating a test Application with a destination you deliberately left unmapped and confirming the sync result matches your decision.
Run a test sync for each destination
For every destination, trigger a sync of a non-production Application and check the resulting events and logs in the Argo CD UI. Confirm the sync runs under the mapped service account rather than the control plane account, and that resource operations succeed with the mapped RBAC. Done means each destination has a recorded successful test, and a deliberately under-privileged test shows the expected denial. Retain the results as evidence of the configuration.
Record the mapping and plan ongoing review
Store the service account mappings, RBAC roles and the enforcement setting in version control alongside the AppProject definitions, so changes go through the same review as other configuration. Assign an owner for reviewing new destinations and RBAC changes. Verify that a fresh review of the repository reproduces the mapping. Each later upgrade should repeat the Beta status check and the test syncs before production use.
Security and operational risks to plan for
Impersonation moves the blast radius of a sync from the control plane account to whichever service account each destination names. The cards below cover where that shift can quietly widen access again, how permissions drift as releases add resource kinds, and which repo-server exposures remain regardless of the account a sync runs as.
Broad accounts recreate the original problem
If the service account mapped to a destination holds cluster-admin or wide namespace rights, impersonation changes the identity on the audit trail but not the damage a bad manifest can do. Grant each destination account only the verbs and resource kinds its applications need, and review the mapping in AppProject destinationServiceAccounts as a privileged configuration, not a routine setting. Ask who approves a new mapping and who can edit AppProjects.
RBAC drift as new kinds appear
Permissions set today can fall behind the manifests tomorrow. Argo CD 3.5 extended impersonation to all server operations, so viewing logs, listing events, deleting resources and running resource actions all depend on the impersonated account's RBAC. When a team adds a new CRD or a new operator, syncs or health checks may fail for that destination, and the quick fix is often a wider role. Schedule a periodic review of each destination account against the kinds its applications actually render.
Keep the control plane account distinct
The control plane account reads repositories, talks to the API and holds the credentials Argo CD needs to reach each cluster. Impersonated accounts should be separate identities that never share tokens, bindings or roles with it. Check that no destination account is bound to the control plane's roles and that the control plane account is not added as a fallback in the destination mapping, since a fallback would bring back the broad access the design removes.
Mapping order and catch-all entries
The first valid match wins, so a broad entry placed above a narrow one silently assigns the wrong account to a destination. A catch-all entry with low priority is recommended, but it is also a path to a default account with more rights than intended. Keep the catch-all minimal, enforce that syncs fail when nothing matches, and test each mapping with a dry run against a non-production cluster before promoting the change.
Repo-server risk from untrusted content
Impersonation limits what a sync can do in the cluster, but it does not limit what the repo-server does before the sync. The repo-server runs Helm and Kustomize on repository content, so an untrusted repository or out-of-tree file access can influence the manifests that reach the destination. Restrict which repositories each project may use, review who can add a repository, and treat impersonation as one control in a chain rather than the whole defense.
What Argo CD 3.5 extended beyond sync
The key point for this section is that in Argo CD 3.5, impersonation is no longer limited to the sync operation. Once application.sync.impersonation.enabled is set in argocd-cm, the destination service account from the matching AppProject entry also governs other server operations on applications in that destination, including viewing logs, listing events, deleting resources and running resource actions. A team that configured impersonation only with sync in mind may find that a user or automation which previously worked now receives permission errors for these actions, or that an account it expected to be read-only can still change resources.
Because of this, impersonated accounts need RBAC verbs that match the operations people and tools perform on each destination. Check the service account bound to each destination against the resources and verbs your operators use day to day, including get and list for events and logs, and delete and any custom action verbs for resources. Review the account in the destination cluster, not only the Argo CD side, since the cluster API server enforces the permissions. Confirm the exact verb set against the current documentation rather than assuming it matches earlier releases.
Teams upgrading from 3.4 to 3.5 should audit these permissions before enabling impersonation, and keep it disabled until the review is complete. Read the upgrade notes for 3.4 to 3.5 in the Argo CD documentation and list every destination that will use a service account, along with the people and pipelines that touch its applications. Test the most common workflows in a non-production cluster first, such as opening logs, reviewing events and restarting a workload. Plan for a rollback path, because failures appear as denied operations in the UI and CLI and can look like Argo CD faults during an incident.
Limits to confirm in your environment
Sync impersonation is a Beta feature, so its behavior is the first thing to confirm against your version. The cards below cover the questions that decide whether it holds up in your environment: release status, patch line, the operations impersonated accounts must reach, and how project boundaries line up with your RBAC design.
Beta status and patch changes
Impersonation shipped as a Beta feature in v3.5.0 and is disabled by default. Before you plan around it, confirm with the Argo CD project whether the Beta label still applies to the release you intend to run, and read the release notes for each patch you adopt. Treat any change to the setting or its behavior in a patch as a change that needs its own test cycle, not a routine update.
Supported patch line fit
Argo CD only ships patch releases for the three most recent minor versions. Impersonation exists only from 3.5 onward, so a team on an older minor must upgrade before it can test the feature at all. Confirm which minor line your organization will standardize on, and plan a patch cadence that stays inside that window so you are not forced onto an unsupported line during a security fix.
Operations impersonated accounts must reach
In 3.5, impersonation covers every server operation, not only the sync. Viewing logs, listing events, deleting resources and running resource actions all execute as the destination service account. Inventory the UI and API operations your operators use per application, then grant each service account the matching verbs. A sync that succeeds while a log view or resource action returns forbidden is a common gap to find in testing.
Project and namespace boundaries
Destination service account matching is driven by the server and namespace of each destination in an AppProject. Confirm that each project's destinations line up with the namespaces your RBAC design assigns to teams, because an application that targets a namespace no entry covers will fail when enforcement is on. Review overlapping project grants so that one team's account is never the default for another team's namespace.
Enforcement and fallback behavior
A sync fails when no destination service account matches, unless enforcement is turned off. Decide whether your organization wants hard failure or a fallback, and test both paths with a deliberately unmatched destination. If you add a low-priority catch-all entry, confirm who owns it, since it determines which privileges any unmatched application inherits and is the first place reviewers will look.
Service account privileges per destination
Impersonation only reduces risk if the service accounts themselves are scoped tightly. Ask who creates and rotates them, which cluster roles they bind, and whether any account holds cluster-wide rights. Confirm the cluster-side audit trail records the impersonated identity, so change reviews can tell which account applied a given manifest.
Questions teams ask before enabling sync impersonation
What drives the cost of enabling sync impersonation in Argo CD?
The main cost driver is how many destinations you must map and how many distinct permission sets those destinations need. Each destination needs a service account in the target cluster, RBAC bindings that grant it only the verbs its applications use, and a matching entry in the AppProject destinationServiceAccounts list. Cost rises with the number of clusters, namespaces and teams, and with how many exceptions the RBAC design carries. Ask a partner to price the work per destination group, the RBAC design review, and the cross-cluster test pass as separate line items. Confirm whether the quote includes work on your existing projects or only new ones.
How long does enabling sync impersonation take?
Duration depends on scope: the number of clusters, the number of AppProjects, how well your current RBAC is documented, and whether the work covers a single pilot destination or a full estate. Impersonation is a Beta feature in v3.5.0 and is disabled by default, so a pilot on one cluster is a reasonable first phase before wider rollout. Ask for a phased timeline in the written scope, with separate milestones for the pilot, the RBAC review and the rollout to remaining destinations. Any date should come from that scope, not from a general estimate.
What must our team provide before the work starts?
You need to supply access to the destination clusters, the Argo CD installation and its AppProjects, and a named RBAC owner for each destination group who can approve the permissions. Test namespaces that mirror production behavior are also important, because impersonated syncs must be verified before enforcement is turned on. Provide the list of resource kinds each application manages, since that determines the verbs each service account needs. Confirm with your cluster administrators who may create service accounts and bindings, and who will receive the change for review.
Can our own platform team enable sync impersonation without a partner?
Yes, a platform team with cluster administration experience and a clear understanding of its applications can enable the feature in-house. The work is configuration in argocd-cm, service accounts and RBAC in each destination, and destinationServiceAccounts entries in each AppProject. The harder part is the inventory: knowing every resource kind and operation each application performs, including logs, events, deletes and resource actions, which 3.5 now covers. A partner is most useful when the estate is large, the RBAC design must be justified to auditors, or the team lacks capacity for cross-cluster testing.
Why do syncs fail after enabling impersonation, and how do we check the RBAC?
Syncs usually fail because the impersonated service account lacks a verb or resource that the sync needs, or because no destinationServiceAccounts entry matches the application's server and namespace. With enforcement on, a sync with no matching entry fails by design. Check the match first, since the first valid entry wins and a low-priority catch-all is recommended. Then test each service account with kubectl auth can-i --as against the resource kinds the application manages, including the verbs used for logs, events and resource actions in 3.5.
What changes after we upgrade Argo CD to a newer version?
Upgrades can change what impersonation covers, so each upgrade needs its own RBAC review. The 3.4 to 3.5 upgrade notes say impersonation extends to all server operations, including viewing logs, listing events, deleting resources and running resource actions, which means accounts that worked for sync may now fail for those operations. Read the upgrade notes for your source and target versions, rerun the permission checks, and confirm that the feature flag and argocd-cm settings still behave as expected. Patch releases follow the project's support policy, so plan upgrades to stay on a supported minor version.
Does sync impersonation remove the need for other Argo CD security controls?
No. Impersonation limits what a sync can do in a destination cluster, but it does not replace SSO, project boundaries, admin account controls or repository trust. The Argo CD security documentation notes that the repo-server runs Helm and Kustomize on repository content, so untrusted repositories remain a risk regardless of which account applies the result. Ask any partner to show how impersonation fits with your existing RBAC, how the change is recorded for auditors, and which controls still need separate work.
How DeployOpen scopes and supports sync impersonation work
DeployOpen starts sync impersonation work with a written scope agreed before anything changes in your clusters. For this feature, that scope lists each AppProject that will carry destinationServiceAccounts, the server and namespace pairs each entry covers, the service account that will act as the default for each destination, and whether application.sync.impersonation.enforced will stay at its default or be set to false during rollout. The scope also states which Argo CD version is in use, since impersonation was introduced as a Beta feature in v3.5.0 and is disabled by default. Fixed scope means the deliverables, the environments involved and the acceptance checks are all written down, so you can compare a partner quote with the cost of doing this with your own team on the same basis.
The build runs inside your own clusters, under your cloud accounts, data centers or air-gapped network, with your existing Argo CD installation and Git repositories. DeployOpen creates the service accounts and the RBAC roles they need on each destination, then verifies each destination separately by running a sync and checking that it succeeds under the intended account. Because the 3.5 release extended impersonation to log viewing, event listing, resource deletion and resource actions, verification also covers those operations, not only the sync itself. DeployOpen documents the resulting service account RBAC, including the verbs granted per destination, so your security and platform teams can review it without reading the cluster directly. Confirm with your own team which platform admins must be able to change these bindings and how changes will be reviewed.
Support after handover is optional and is offered as a retainer. Upgrades matter here because each minor Argo CD release, and the 3.4 to 3.5 change in particular, can alter what an impersonated account must be allowed to do. Ask any partner, including DeployOpen, how a retainer covers testing of each new patch and minor release against your destination RBAC, how new applications and destinations are added to the mapping, and who is on the hook when a sync fails for a permission reason at 2 a.m. Retainer terms are set in writing like the initial scope, and they recur on a schedule you agree rather than being part of the one-time build.
