Comparing EKS Capability for Argo CD to self-managed Argo CD

The EKS Capability for Argo CD provides a fully managed Argo CD experience that runs in EKS. For a general comparison of EKS Capabilities vs self-managed solutions, see EKS Capabilities considerations. This topic focuses on Argo CD-specific differences, including authentication, multi-cluster management, and upstream feature support.

Differences from upstream Argo CD

The EKS Capability for Argo CD is based on upstream Argo CD but differs in how it’s accessed, configured, and integrated with AWS services.

RBAC and authentication: The capability comes with three RBAC roles (admin, editor, viewer) and uses AWS Identity Center for authentication instead of Argo CD’s built-in authentication. Configure role mappings through the capability’s rbacRoleMapping parameter to map Identity Center groups to Argo CD roles, not through Argo CD’s argocd-rbac-cm ConfigMap. The Argo CD UI is hosted with its own direct URL (find it in the EKS console under your cluster’s Capabilities page), and API access uses AWS authentication and authorization through IAM.

Cluster configuration: The capability does not automatically configure local cluster or hub-and-spoke topologies. You configure your deployment target clusters and EKS access entries. The capability supports only Amazon EKS clusters as deployment targets using EKS cluster ARNs (not Kubernetes API server URLs). The capability does not automatically add the local cluster (kubernetes.default.svc) as a deployment target—to deploy to the same cluster where the capability is created, explicitly register that cluster using its ARN.

Simplified remote cluster access: The capability simplifies multi-cluster deployments by using EKS Access Entries to grant Argo CD access to remote clusters, eliminating the need to configure IAM Roles for Service Accounts (IRSA) or set up cross-account IAM role assumptions. The capability also provides transparent access to fully private EKS clusters without requiring VPC peering or specialized networking configuration—AWS manages connectivity between the Argo CD capability and private remote clusters automatically.

Direct AWS service integration: The capability provides direct integration with AWS services through the Capability Role’s IAM permissions. You can reference CodeCommit repositories, ECR Helm charts, and CodeConnections directly in Application resources without creating Repository configurations. This simplifies authentication and eliminates the need to manage separate credentials for AWS services. See Configure repository access for details.

Source hydrator: Upstream Argo CD disables the source hydrator by default. To use it with the capability, add hydrator.enabled: "true" to argocd-cmd-params-cm, and then configure spec.sourceHydrator in your Application. The source hydrator renders manifests (for example, from Helm charts or Kustomize overlays) and pushes the rendered output to Git before syncing to the cluster. For instructions on using the source hydrator, see Push hydrated manifests with the source hydrator.

Webhook endpoints: Upstream Argo CD serves the Applications receiver and the ApplicationSet receiver on the same /api/webhook path. It tells them apart by hostname, which requires a second Ingress. Because each Argo CD instance has one hostname, the capability serves the ApplicationSet receiver on /api/applicationset/webhook instead. The capability also reads webhook shared secrets from the argocd-webhook-creds-secret Secret rather than from argocd-secret. You can therefore manage webhook credentials without access to the Argo CD server’s signing key and TLS material. For more information about webhook configuration, see Webhook configuration for faster sync.

Notifications: The capability runs the notifications controller, but reads configuration from argocd-notifications-cm only when that ConfigMap carries the eks.amazonaws.com/managed-notifications: "enabled" label. It supports 15 upstream service types plus eventbridge, which the capability adds, and does not support the email, teams, webhook, rocketchat, nats, or alertmanager types. The awssqs and eventbridge services authenticate with the IAM Capability Role instead of credentials in the Secret, and you can store any credential as an AWS Secrets Manager ARN. For more information, see Send notifications for Argo CD Applications.

Namespace support: You specify a primary Argo CD namespace when you create the capability. AppProject resources, Argo CD configuration, and repository and cluster credentials remain in this namespace. You can configure additional namespaces for Application and ApplicationSet resources by using the argocd-cmd-params-cm ConfigMap. For instructions on configuring additional namespaces, see Configure namespaces for Applications and ApplicationSets.

Note

The namespace that contains an Application or ApplicationSet is separate from the destination namespace where the generated workload runs. For example, an Application stored in team-a-gitops can deploy workloads to default, production, staging, or another namespace in a target cluster.

Note

The managed capability has specific requirements for CLI usage, AppProject configuration, resource tracking, and ApplicationSet generators:

• When using the Argo CD CLI, specify resources outside the primary namespace with a namespace prefix, such as argocd app sync team-a-gitops/my-app.

• AppProject resources must specify .spec.sourceNamespaces to allow Applications and ApplicationSets from each additional namespace.

• Resource tracking annotations use the format: namespace_appname:group/kind:namespace/name.

• ApplicationSets in additional namespaces don’t support the Plugin (plugin), Pull Request (pullRequest), or Source Code Management (SCM) Provider (scmProvider) generators. To use one of these generators, create the ApplicationSet in the primary Argo CD namespace.

Unsupported features: The following features are not available in the managed capability:

• Config Management Plugins (CMPs) for custom manifest generation

• Custom SSO providers (only AWS Identity Center is supported, including third-party federated identity through AWS Identity Center)

• UI extensions

• Argo CD configuration ConfigMaps and keys other than the supported argocd-cm fields, the argocd-notifications-cm keys described in Send notifications for Argo CD Applications, and the hydrator.enabled, application.namespaces, applicationsetcontroller.namespaces, and notificationscontroller.selfservice.enabled keys in argocd-cmd-params-cm. See Configure Argo CD settings.

• Modifying the sync timeout (fixed at 120 seconds)

Compatibility: The capability uses the same Kubernetes APIs and CRDs as upstream Argo CD, so existing Application and ApplicationSet manifests generally require no changes. Tools like kubectl work the same way. Except for the limitations described in this topic, the capability supports Applications and ApplicationSets, GitOps workflows with automatic sync, multi-cluster deployments, sync policies (automated, prune, self-heal), sync waves and hooks, health assessment for standard Kubernetes resources, custom health checks for Custom Resources (see Custom health checks), rollback capabilities, Git repository sources (HTTPS and SSH), Helm, Kustomize, and plain YAML manifests, GitHub app credentials, projects for multi-tenancy, and resource exclusions and inclusions.

Migration path

You can migrate from self-managed Argo CD to the managed capability:

1. Review your current Argo CD configuration for unsupported features (CMPs, UI extensions)

2. Scale your self-managed Argo CD controllers to zero replicas to prevent conflicts

3. Create an Argo CD capability resource on your cluster

4. Export your existing Applications, ApplicationSets, and AppProjects

5. Migrate repository credentials, cluster secrets, and repository credential templates (repocreds)

6. If using GPG keys, TLS certificates, or SSH known hosts, migrate these configurations as well

7. Update destination.server fields to use cluster names or EKS cluster ARNs

8. Apply them to the managed Argo CD instance

9. Verify applications are syncing correctly

10. Decommission your self-managed Argo CD installation

The managed capability uses the same Argo CD APIs and resource definitions, so your existing manifests work with minimal modification.

Next steps

• Create an Argo CD capability - Create an Argo CD capability resource

• Working with Argo CD - Deploy your first application

• Argo CD considerations - Configure AWS Identity Center integration