Reaching a managed Argo CD on Amazon EKS: endpoints, identity and hub-and-spoke

The EKS Capability for Argo CD does not run in your cluster, so the usual playbook of an Ingress, a load balancer and a Dex config does not apply. This is how an enterprise actually reaches it: which endpoint people hit, how to take it off the internet, who can sign in, how pipelines authenticate, and how one instance reaches clusters in other accounts.

1Where the managed Argo CD actually runs

With a self-managed install, Argo CD is a set of pods in your cluster, and exposing it means an Ingress, a load balancer, a certificate and a DNS record. The EKS Capability for Argo CD changes that. AWS runs the Argo CD controllers, the repo server and the API server in its own infrastructure, outside your account. Your worker nodes never run an Argo CD pod and do not need a network path to Git or to Helm registries.

What stays in your cluster is the data. The Argo CD custom resources (Application, ApplicationSet, AppProject) and the cluster registration Secrets live in a namespace you choose when you create the capability, usually argocd. EKS installs the custom resource definitions for you, and you manage these objects with kubectl or Git like any other manifest.

The endpoint has the form https://{capability-name}-{hash}-{account-id}.eks-capabilities.{region}.amazonaws.com. You can set an optional endpointPrefix for a friendlier hostname. Find the URL in the EKS console (your cluster, then the Capabilities tab, then Open Argo CD UI), or with the AWS CLI once the capability is ACTIVE:

aws eks describe-capability \
  --region us-east-1 \
  --cluster-name platform-hub \
  --capability-name argocd \
  --query 'capability.configuration.argoCd.serverUrl' \
  --output text

That one hostname is the whole access surface. The UI, the API, the CLI over gRPC-web and Git webhooks (${serverUrl}/api/webhook) all use it. Every access decision in the rest of this article is about who can reach that hostname, and who they are once they get there.

2The default: a public endpoint behind Identity Center

Out of the box, the endpoint is reachable from the internet. Anyone can reach the sign-in page, but nobody gets past it without an IAM Identity Center identity that you have mapped to an Argo CD role. For a proof of concept, or for an organization whose access model is "the identity provider is the perimeter", that can be enough.

Two things push most enterprises past this default. Security reviews usually want deployment tooling unreachable from the internet, whatever the authentication. And the public path is also the path a stolen token would use: a token works from anywhere the endpoint is reachable.

3Private-only access from the corporate network

To take the endpoint off the internet, create an interface VPC endpoint (AWS PrivateLink) for the service com.amazonaws.{region}.eks-capabilities and attach its ID to the capability. Three things change at once:

• Public access to the Argo CD endpoint is blocked.
• AWS updates DNS so that the same hostname resolves to the private IP addresses of your VPC endpoint. You do not need a new name or a new certificate.
• Anyone who wants in needs network connectivity to those private IPs: from the VPC itself, or from networks connected to it through VPN or AWS Direct Connect.

In an enterprise, that VPC is usually a shared-services or network VPC already attached to a Transit Gateway, so on-premises users ride the existing Direct Connect or VPN path:

Steps 1 and 2 are the standard way to resolve private AWS names from on premises, not something the capability docs prescribe. Those docs say the hostname resolves to the endpoint's private IPs, and tell you to verify it with nslookup "from any network", which suggests public DNS already returns the private answer. Check what your corporate resolvers return first. If they already get the private IPs, you can skip the forwarder.

# Subnets in at least two Availability Zones.
# The security group must allow inbound 443 from every client network.
aws ec2 create-vpc-endpoint \
  --region us-east-1 \
  --vpc-endpoint-type Interface \
  --service-name com.amazonaws.us-east-1.eks-capabilities \
  --vpc-id vpc-0a1b2c3d4e5f60718 \
  --subnet-ids subnet-0aa11bb22cc33dd44 subnet-0ee55ff66aa77bb88 \
  --security-group-ids sg-0123abcd4567ef890

# Wait for the endpoint state to be "available" first.
aws eks update-capability \
  --region us-east-1 \
  --cluster-name platform-hub \
  --capability-name argocd \
  --configuration '{
    "argoCd": {
      "networkAccess": { "vpceIds": ["vpce-0123456789abcdef0"] }
    }
  }'

# Status returns to ACTIVE when the update completes.
aws eks describe-capability --region us-east-1 \
  --cluster-name platform-hub --capability-name argocd \
  --query 'capability.status' --output text

# Should return RFC 1918 addresses (10.x, 172.16-31.x, 192.168.x).
nslookup argocd-a1b2c3d4-111122223333.eks-capabilities.us-east-1.amazonaws.com

# An empty list restores public access.
aws eks update-capability \
  --region us-east-1 \
  --cluster-name platform-hub \
  --capability-name argocd \
  --configuration '{ "argoCd": { "networkAccess": { "vpceIds": [] } } }'

A few rules from the docs shape the design:

• Private access applies at creation or later. At creation you can pass the endpoint ID in the capability configuration (networkAccess.vpceIds), or with the --network-configuration parameter shown in the CLI guide. On an existing capability, use update-capability.
• vpceIds is a list. You can attach more than one endpoint, for example one in each network VPC that users come from.
• The security group is your network control. AWS does not currently support VPC endpoint policies for the eks-capabilities service, so the endpoint's security group (source CIDRs on port 443) is the only network-level filter.
• The endpoint is now load-bearing. If you delete it, nobody can reach Argo CD until you create a new one and update the capability. Protect it like any other shared network resource.

Several Argo CD instances behind one endpoint

Large organizations rarely stop at one Argo CD. A platform team runs one for shared services, and a regulated business unit runs its own. Each instance is a separate capability on its own cluster, but they do not each need their own VPC endpoint. The endpoint is for the Region-wide eks-capabilities service, not for one capability, and each capability simply lists its ID in vpceIds.

DNS is what keeps the instances apart. Every capability has its own hostname: {capability-name}-{hash}-{account-id} by default, or {prefix}-{account-id} if you set an endpoint prefix, which must be unique in the account and Region. When private access is on, AWS publishes a record for each hostname that points at the private IPs of the endpoint it lists. The docs tell you to verify this with nslookup "from any network", so these are AWS-managed records, not a private hosted zone you create.

Two caveats. First, the AWS documentation does not state outright that two capabilities can list the same endpoint, or that routing is by hostname. Steps 2 to 4 are how other shared AWS interface endpoints behave, such as private API Gateway, and what the per-instance hostnames imply. Confirm it with two capabilities before you depend on it. Second, the documented multi-endpoint case is the reverse: one capability listing several endpoints, "to enable access from multiple VPCs". Each hostname has one public record, and the docs do not say which endpoint's IPs it returns when it lists endpoints in two VPCs. One central endpoint in a network VPC that every other network routes to sidesteps both questions: one set of IPs, one security group, and any number of Argo CD instances behind it.

4Identity: Identity Center is the only way in

The capability authenticates people only through IAM Identity Center. The awsIdc block (the Identity Center instance ARN, plus an optional Region if the instance lives in a different Region from the cluster) is required when you create the capability. Local Argo CD users, Dex and custom OIDC or SAML providers are not supported. Corporate identity providers such as Okta, Entra ID or ADFS work only by federating into Identity Center, which most AWS organizations already do.

Authorization has two levels, and both have to say yes:

• Global roles are fixed. ADMIN can do everything, including registering clusters and repositories. EDITOR can update existing projects and their roles but cannot change global settings, clusters or repositories. VIEWER is read-only. Role names are case-sensitive uppercase.
• EDITOR and VIEWER see no Applications by default. They need a project role. ADMIN sees everything without one.
• Mappings use IDs, not names. Both rbacRoleMappings and AppProject groups take Identity Center user and group IDs.
• There is a ceiling. One capability supports up to 1,000 identities, counting users and groups. Map groups, not people.

The pattern the AWS docs recommend for teams: the platform team maps to ADMIN, team leads to EDITOR, and all developers to VIEWER. ADMIN creates one AppProject per team, and each team lead grants their developers project roles inside it.

aws eks update-capability \
  --region us-east-1 \
  --cluster-name platform-hub \
  --capability-name argocd \
  --configuration '{
    "argoCd": {
      "rbacRoleMappings": {
        "addOrUpdateRoleMappings": [
          { "role": "ADMIN",
            "identities": [{ "id": "<platform-team-group-id>", "type": "SSO_GROUP" }] },
          { "role": "EDITOR",
            "identities": [{ "id": "<team-leads-group-id>", "type": "SSO_GROUP" }] },
          { "role": "VIEWER",
            "identities": [{ "id": "<all-developers-group-id>", "type": "SSO_GROUP" }] }
        ]
      }
    }
  }'

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: payments
  namespace: argocd
spec:
  sourceNamespaces:            # required by the managed capability
    - argocd
  sourceRepos:
    - https://github.com/acme/payments-deploy
  destinations:
    - server: arn:aws:eks:us-east-1:222233334444:cluster/prod-a
      namespace: 'payments-*'
  roles:
    - name: developer
      policies:
        - p, proj:payments:developer, applications, *, payments/*, allow
        - p, proj:payments:developer, clusters, get, *, allow   # show cluster names in the UI
      groups:
        - <payments-devs-group-id>   # Identity Center group ID

The identity type is SSO_GROUP for groups and SSO_USER for individual users. One more point from the docs: Argo CD permissions are not Kubernetes permissions. Anyone who can create an Application can deploy to any cluster Argo CD can reach, within their project's limits. Keep each project's destinations narrow.

5The CLI and CI/CD without argocd login

The Argo CD CLI works against the managed endpoint, but not through SSO. argocd login is not supported, and neither are argocd admin commands, which need direct pod access. You set three environment variables instead:

export ARGOCD_SERVER=$(aws eks describe-capability \
  --region us-east-1 --cluster-name platform-hub --capability-name argocd \
  --query 'capability.configuration.argoCd.serverUrl' --output text | sed 's|^https://||')
export ARGOCD_AUTH_TOKEN="<token generated in the Argo CD UI>"
export ARGOCD_OPTS="--grpc-web"

argocd app list
argocd app sync payments/checkout-api

• Admin account tokens are for setup only. Generate one under Settings, Accounts, admin. Only 5 can exist at a time, and AWS recommends an expiry of 12 hours at most.
• Pipelines use project-role tokens. A token scoped to one AppProject role can sync that project's Applications and nothing else. Store it in your CI system's secret store and rotate it.
• The pipeline needs the same network path as people. With private access on, a hosted runner on the internet cannot reach the endpoint. Run deployment jobs on runners inside the connected network, or let Git drive the sync and keep the pipeline out of Argo CD entirely.
• AWS-side calls are separate. describe-capability, update-capability and access entry calls are ordinary AWS API calls, controlled by IAM.

6Hub-and-spoke across accounts and Regions

The fleet design is one capability on a hub cluster in a platform account, deploying to workload clusters in other accounts. The capability does not set up this topology, or even the local cluster, for you. You register every target, including the hub itself, and grant access on each one.

Compared with a self-managed hub, three parts of the usual design disappear:

• No IRSA or role chaining. You do not create roles in the spoke accounts or write cross-account trust policies. The Access Entry on the target cluster names the hub's capability role directly.
• No network path. AWS manages connectivity from the capability to target clusters, including fully private ones. You don't need VPC peering, Transit Gateway routes or a public API endpoint on the spokes.
• Regions are not special. The cluster ARN includes the Region, so a cross-Region target is registered the same way as a local one.

# Run in the workload account, against the target cluster.
aws eks create-access-entry \
  --region us-east-1 \
  --cluster-name prod-a \
  --principal-arn arn:aws:iam::111122223333:role/ArgoCDCapabilityRole \
  --type STANDARD

# Write access only where this cluster's apps live.
aws eks associate-access-policy \
  --region us-east-1 \
  --cluster-name prod-a \
  --principal-arn arn:aws:iam::111122223333:role/ArgoCDCapabilityRole \
  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSEditPolicy \
  --access-scope type=namespace,namespaces=payments-prod

# Argo CD must READ every resource type cluster-wide for health checks
# and drift detection, even if it only WRITES to a few namespaces.
aws eks associate-access-policy \
  --region us-east-1 \
  --cluster-name prod-a \
  --principal-arn arn:aws:iam::111122223333:role/ArgoCDCapabilityRole \
  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSAdminViewPolicy \
  --access-scope type=cluster

# Committed to Git, or applied to the hub cluster.
apiVersion: v1
kind: Secret
metadata:
  name: prod-a
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: cluster
    env: prod                      # ApplicationSet cluster generators select on labels
stringData:
  name: prod-a
  server: arn:aws:eks:us-east-1:222233334444:cluster/prod-a   # the ARN, never the API URL
  project: payments

• The hub needs registering too. EKS creates an Access Entry for the capability role on the hub cluster, but with no Kubernetes permissions. If the hub only manages other clusters, leave it that way. If it also runs workloads, register it by ARN (the docs suggest the name in-cluster for compatibility with upstream examples) and grant it permissions like any spoke.
• Do not ship AmazonEKSClusterAdminPolicy. The docs use it to get started quickly and warn against it in production, because it is equivalent to system:masters. Use cluster-wide read access plus namespace-scoped write access.
• Grant reads with an access policy, not a ClusterRole. The AWS docs show a ClusterRole bound to the group eks-access-entry:<role-ARN>. On a test build of this design, that binding never applied: Argo CD failed with apiservices.apiregistration.k8s.io is forbidden and the Application stayed Unknown. Associating AmazonEKSAdminViewPolicy at cluster scope fixed it within a minute. It also keeps every permission in one place, the Access Entry.
• Only EKS clusters can be targets. An on-premises or other-cloud cluster has no EKS ARN to register.
• Registration status starts at Unknown. A new cluster shows an Unknown connection state until an Application targets it. That does not mean registration failed.

7Managed or self-managed

Almost every access decision above is simpler than its self-managed equivalent. The price is a list of things you cannot change.

Choose the managed capability when every target is EKS, Identity Center is already how people get into AWS, and nobody depends on notifications, plugins or custom RBAC rules. Stay self-managed when you need non-EKS targets, a sign-in path that cannot go through Identity Center, Argo CD notifications, Config Management Plugins, or fine-grained global policies. Moving across is supported. AWS documents a migration path: scale the old controllers to zero, export Applications, ApplicationSets and AppProjects, and rewrite destination.server to cluster ARNs.

8What the documentation does not answer yet

The capability launched in late 2025, and some questions an enterprise review will ask are not covered in the AWS documentation used here. Test these yourself before you commit:

• Whether the EKS console's Open Argo CD UI link still works from a browser outside the connected network once public access is blocked. Based on the DNS behavior, expect it not to.
• How Git webhooks from a SaaS Git host reach a private-only endpoint. The webhook source is on the internet, so plan on polling or a relay inside your network.
• Where actions inside Argo CD (syncs, sign-ins, RBAC decisions) are audited, and whether they reach CloudTrail.
• Which private IPs a hostname resolves to when one capability lists endpoints in two different VPCs.
• Per-capability limits on registered clusters or Applications beyond the identity and token limits, and the pricing at fleet scale.

Conclusion

Access to a managed Argo CD is a short list of decisions, none of which involve Kubernetes networking. Decide whether the endpoint stays public or goes behind an eks-capabilities VPC endpoint in a network VPC that your hybrid links already reach. Decide which Identity Center groups get ADMIN, EDITOR and VIEWER, and give each team an AppProject with narrow destinations. Give pipelines project tokens and a runner that can reach the endpoint. Then grant one Access Entry per target cluster, with read access everywhere and write access only where that team deploys. The load balancers, certificates, Dex configuration and cross-account trust chains that a self-managed hub needs are simply gone. What remains is what you cannot customize, and that list decides whether the managed capability fits.

References

• Amazon EKS User Guide: Continuous deployment with Argo CD, Argo CD considerations, Comparing EKS Capability for Argo CD to self-managed Argo CD.
• Amazon EKS User Guide: Create an Argo CD capability using the AWS CLI, Configure private endpoint access for Argo CD.
• Amazon EKS User Guide: Configure Argo CD permissions, Register target clusters.
• Amazon EKS API Reference: ArgoCdConfigRequest and ArgoCdConfigResponse.
• AWS Containers Blog: Deep dive: streamlining GitOps with Amazon EKS Capability for Argo CD. AWS News Blog: Announcing Amazon EKS Capabilities.