**Help improve this page**
To contribute to this user guide, choose the **Edit this page on GitHub** link that is located in the right pane of every page.
# Continuous Deployment with Argo CD
Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes. With Argo CD, you can automate the deployment and lifecycle management of your applications across multiple clusters and environments. Argo CD supports multiple source types including Git repositories, Helm registries (HTTP and OCI), and OCI images—providing flexibility for organizations with different security and compliance requirements.
With EKS Capabilities, Argo CD is fully managed by AWS, eliminating the need to install, maintain, and scale Argo CD controllers and their dependencies on your clusters.
## How Argo CD Works
Argo CD follows the GitOps pattern, where your application source (Git repository, Helm registry, or OCI image) is the source of truth for defining the desired application state. When you create an Argo CD `Application` resource, you specify the source containing your application manifests and the target Kubernetes cluster and namespace. Argo CD continuously monitors both the source and the live state in the cluster, automatically synchronizing any changes to ensure the cluster state matches the desired state.
**Note**
With the EKS Capability for Argo CD, the Argo CD software runs in the AWS control plane, not on your worker nodes. This means your worker nodes don’t need direct access to Git repositories or Helm registries—the capability handles source access from the AWS account.
Argo CD provides three primary resource types:
+ **Application**: Defines a deployment from a Git repository to a target cluster
+ **ApplicationSet**: Generates multiple Applications from templates for multi-cluster deployments
+ **AppProject**: Provides logical grouping and access control for Applications
**Example: Creating an Argo CD Application**
The following example shows how to create an Argo CD `Application` resource:
```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: guestbook
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/argoproj/argocd-example-apps.git
targetRevision: HEAD
path: guestbook
destination:
name: in-cluster
namespace: guestbook
syncPolicy:
automated:
prune: true
selfHeal: true
```
**Note**
Use `destination.name` with the cluster name you used when registering the cluster (like `in-cluster` for the local cluster). The `destination.server` field also works with EKS cluster ARNs, but using cluster names is recommended for better readability.
## Benefits of Argo CD
Argo CD implements a GitOps workflow where you define your application configurations in Git repositories and Argo CD automatically syncs your applications to match the desired state. This Git-centric approach provides a complete audit trail of all changes, enables easy rollbacks, and integrates naturally with your existing code review and approval processes. Argo CD automatically detects and reconciles drift between the desired state in Git and the actual state in your clusters, ensuring your deployments remain consistent with your declared configuration.
With Argo CD, you can deploy and manage applications across multiple clusters from a single Argo CD instance, simplifying operations in multi-cluster and multi-region environments. The Argo CD UI provides visualization and monitoring capabilities, allowing you to view the deployment status, health, and history of your applications. The UI integrates with AWS Identity Center (formerly AWS SSO) for seamless authentication and authorization, enabling you to control access using your existing identity management infrastructure.
As part of EKS Managed Capabilities, Argo CD is fully managed by AWS, eliminating the need to install, configure, and maintain Argo CD infrastructure. AWS handles scaling, patching, and operational management, allowing your teams to focus on application delivery rather than tool maintenance.
## Integration with AWS Identity Center
EKS Managed Capabilities provides direct integration between Argo CD and AWS Identity Center, enabling seamless authentication and authorization for your users. When you enable the Argo CD capability, you can configure AWS Identity Center integration to map Identity Center groups and users to Argo CD RBAC roles, allowing you to control who can access and manage applications in Argo CD.
## Integration with Other EKS Managed Capabilities
Argo CD integrates with other EKS Managed Capabilities.
+ ** AWS Controllers for Kubernetes (ACK)**: Use Argo CD to manage the deployment of ACK resources across multiple clusters, enabling GitOps workflows for your AWS infrastructure.
+ **kro (Kube Resource Orchestrator)**: Use Argo CD to deploy kro compositions across multiple clusters, enabling consistent resource composition across your Kubernetes estate.
## Getting Started with Argo CD
To get started with the EKS Capability for Argo CD:
1. Create and configure an IAM Capability Role with the necessary permissions for Argo CD to access your sources and manage applications.
1. [Create an Argo CD capability resource](create-argocd-capability.md) on your EKS cluster through the AWS Console, AWS CLI, or your preferred infrastructure as code tool.
1. Configure repository access and register clusters for application deployment.
1. Create Application resources to deploy your applications from your declarative sources.
# Create an Argo CD capability
This topic explains how to create an Argo CD capability on your Amazon EKS cluster.
## Prerequisites
Before creating an Argo CD capability, ensure you have:
+ An existing Amazon EKS cluster running a supported Kubernetes version (all versions in standard and extended support are supported)
+ ** AWS Identity Center configured** - Required for Argo CD authentication (local users are not supported)
+ An IAM Capability Role with permissions for Argo CD
+ Sufficient IAM permissions to create capability resources on EKS clusters
+ `kubectl` configured to communicate with your cluster
+ (Optional) The Argo CD CLI installed for easier cluster and repository management
+ (For CLI/eksctl) The appropriate CLI tool installed and configured
For instructions on creating the IAM Capability Role, see [Amazon EKS capability IAM role](capability-role.md). For Identity Center setup, see [Getting started with AWS Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html).
**Important**
The IAM Capability Role you provide determines which AWS resources Argo CD can access. This includes Git repository access via CodeConnections and secrets in Secrets Manager. For guidance on creating an appropriate role with least-privilege permissions, see [Amazon EKS capability IAM role](capability-role.md) and [Security considerations for EKS Capabilities](capabilities-security.md).
## Choose your tool
You can create an Argo CD capability using the AWS Management Console, AWS CLI, or eksctl:
+ [Create an Argo CD capability using the Console](argocd-create-console.md) - Use the Console for a guided experience
+ [Create an Argo CD capability using the AWS CLI](argocd-create-cli.md) - Use the AWS CLI for scripting and automation
+ [Create an Argo CD capability using eksctl](argocd-create-eksctl.md) - Use eksctl for a Kubernetes-native experience
## What happens when you create an Argo CD capability
When you create an Argo CD capability:
1. EKS creates the Argo CD capability service in the AWS control plane
1. Custom Resource Definitions (CRDs) are installed in your cluster
1. An access entry is automatically created for your IAM Capability Role with capability-specific access entry policies that grant baseline Kubernetes permissions (see [Security considerations for EKS Capabilities](capabilities-security.md))
1. Argo CD begins watching for its custom resources (Applications, ApplicationSets, AppProjects)
1. The capability status changes from `CREATING` to `ACTIVE`
1. The Argo CD UI becomes accessible through its URL
Once active, you can create Argo CD Applications in your cluster to deploy from your declarative sources.
**Note**
The automatically created access entry does not grant permissions to deploy applications to clusters. To deploy applications, you must configure additional Kubernetes RBAC permissions for each target cluster. See [Register target clusters](argocd-register-clusters.md) for details on registering clusters and configuring access.
## Next steps
After creating the Argo CD capability:
+ [Argo CD concepts](argocd-concepts.md) - Learn about GitOps principles, sync policies, and multi-cluster patterns
+ [Working with Argo CD](working-with-argocd.md) - Configure repository access, register target clusters, and create Applications
+ [Argo CD considerations](argocd-considerations.md) - Explore multi-cluster architecture patterns and advanced configuration
# Create an Argo CD capability using the Console
This topic describes how to create an Argo CD capability using the AWS Management Console.
## Prerequisites
+ ** AWS Identity Center configured** – Argo CD requires AWS Identity Center for authentication. Local users are not supported. If you don’t have AWS Identity Center set up, see [Getting started with AWS Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html) to create an Identity Center instance, and [Add users](https://docs.aws.amazon.com/singlesignon/latest/userguide/addusers.html) and [Add groups](https://docs.aws.amazon.com/singlesignon/latest/userguide/addgroups.html) to create users and groups for Argo CD access.
## Create the Argo CD capability
1. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home\$1/clusters.
1. Select your cluster name to open the cluster detail page.
1. Choose the **Capabilities** tab.
1. In the left navigation, choose **Argo CD**.
1. Choose **Create Argo CD capability**.
1. For **IAM Capability Role**:
+ If you already have an IAM Capability Role, select it from the dropdown
+ If you need to create a role, choose **Create Argo CD role**
This opens the IAM console in a new tab with pre-populated trust policy and full read access to Secrets Manager. No other permissions are added by default, but you can add them if needed. If you plan to use CodeCommit repositories or other AWS services, add the appropriate permissions before creating the role.
After creating the role, return to the EKS console and the role will be automatically selected.
**Note**
If you plan to use the optional integrations with AWS Secrets Manager or AWS CodeConnections, you’ll need to add permissions to the role. For IAM policy examples and configuration guidance, see [Manage application secrets with AWS Secrets Manager](integration-secrets-manager.md) and [Connect to Git repositories with AWS CodeConnections](integration-codeconnections.md).
1. Configure AWS Identity Center integration:
1. Select **Enable AWS Identity Center integration**.
1. Choose your Identity Center instance from the dropdown.
1. Configure role mappings for RBAC by assigning users or groups to Argo CD roles (ADMIN, EDITOR, or VIEWER)
1. Choose **Create**.
The capability creation process begins.
## Verify the capability is active
1. On the **Capabilities** tab, view the Argo CD capability status.
1. Wait for the status to change from `CREATING` to `ACTIVE`.
1. Once active, the capability is ready to use.
For information about capability statuses and troubleshooting, see [Working with capability resources](working-with-capabilities.md).
## Access the Argo CD UI
After the capability is active, you can access the Argo CD UI:
1. On the Argo CD capability page, choose **Open Argo CD UI**.
1. The Argo CD UI opens in a new browser tab.
1. You can now create Applications and manage deployments through the UI.
## Next steps
+ [Working with Argo CD](working-with-argocd.md) - Configure repositories, register clusters, and create Applications
+ [Argo CD considerations](argocd-considerations.md) - Multi-cluster architecture and advanced configuration
+ [Working with capability resources](working-with-capabilities.md) - Manage your Argo CD capability resource
# Create an Argo CD capability using the AWS CLI
This topic describes how to create an Argo CD capability using the AWS CLI.
## Prerequisites
+ ** AWS CLI** – Version `2.12.3` or later. To check your version, run `aws --version`. For more information, see [Installing](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) in the AWS Command Line Interface User Guide.
+ ** `kubectl` ** – A command line tool for working with Kubernetes clusters. For more information, see [Set up `kubectl` and `eksctl`](install-kubectl.md).
+ ** AWS Identity Center configured** – Argo CD requires AWS Identity Center for authentication. Local users are not supported. If you don’t have AWS Identity Center set up, see [Getting started with AWS Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html) to create an Identity Center instance, and [Add users](https://docs.aws.amazon.com/singlesignon/latest/userguide/addusers.html) and [Add groups](https://docs.aws.amazon.com/singlesignon/latest/userguide/addgroups.html) to create users and groups for Argo CD access.
## Step 1: Create an IAM Capability Role
Create a trust policy file:
```
cat > argocd-trust-policy.json << 'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "capabilities.eks.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession"
]
}
]
}
EOF
```
Create the IAM role:
```
aws iam create-role \
--role-name ArgoCDCapabilityRole \
--assume-role-policy-document file://argocd-trust-policy.json
```
**Note**
If you plan to use the optional integrations with AWS Secrets Manager or AWS CodeConnections, you’ll need to add permissions to the role. For IAM policy examples and configuration guidance, see [Manage application secrets with AWS Secrets Manager](integration-secrets-manager.md) and [Connect to Git repositories with AWS CodeConnections](integration-codeconnections.md).
## Step 2: Create the Argo CD capability
Create the Argo CD capability resource on your cluster.
First, set environment variables for your Identity Center configuration:
```
# Get your Identity Center instance ARN (replace region if your IDC instance is in a different region)
export IDC_INSTANCE_ARN=$(aws sso-admin list-instances --region [.replaceable]`region` --query 'Instances[0].InstanceArn' --output text)
# Get a user ID for RBAC mapping (replace with your username and region if needed)
export IDC_USER_ID=$(aws identitystore list-users \
--region [.replaceable]`region` \
--identity-store-id $(aws sso-admin list-instances --region [.replaceable]`region` --query 'Instances[0].IdentityStoreId' --output text) \
--query 'Users[?UserName==`your-username`].UserId' --output text)
echo "IDC_INSTANCE_ARN=$IDC_INSTANCE_ARN"
echo "IDC_USER_ID=$IDC_USER_ID"
```
Create the capability with Identity Center integration. Replace *region-code* with the AWS Region where your cluster is located and *my-cluster* with your cluster name and *idc-region-code* with the region code where you IAM Identity Center has been configured:
```
aws eks create-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-argocd \
--type ARGOCD \
--role-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):role/ArgoCDCapabilityRole \
--delete-propagation-policy RETAIN \
--configuration '{
"argoCd": {
"awsIdc": {
"idcInstanceArn": "'$IDC_INSTANCE_ARN'",
"idcRegion": "'[.replaceable]`idc-region-code`'"
},
"rbacRoleMappings": [{
"role": "ADMIN",
"identities": [{
"id": "'$IDC_USER_ID'",
"type": "SSO_USER"
}]
}]
}
}'
```
The command returns immediately, but the capability takes some time to become active as EKS creates the required capability infrastructure and components. EKS will install the Kubernetes Custom Resource Definitions related to this capability in your cluster as it is being created.
**Note**
If you receive an error that the cluster doesn’t exist or you don’t have permissions, verify:
The cluster name is correct
Your AWS CLI is configured for the correct region
You have the required IAM permissions
## Step 3: Verify the capability is active
Wait for the capability to become active. Replace *region-code* with the AWS Region where your cluster is located and *my-cluster* with your cluster name.
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-argocd \
--query 'capability.status' \
--output text
```
The capability is ready when the status shows `ACTIVE`. Don’t continue to the next step until the status is `ACTIVE`.
You can also view the full capability details:
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-argocd
```
## Step 4: Verify custom resources are available
After the capability is active, verify that Argo CD custom resources are available in your cluster:
```
kubectl api-resources | grep argoproj.io
```
You should see `Application` and `ApplicationSet` resource types listed.
## Next steps
+ [Working with Argo CD](working-with-argocd.md) - Configure repositories, register clusters, and create Applications
+ [Argo CD considerations](argocd-considerations.md) - Multi-cluster architecture and advanced configuration
+ [Working with capability resources](working-with-capabilities.md) - Manage your Argo CD capability resource
# Create an Argo CD capability using eksctl
This topic describes how to create an Argo CD capability using eksctl.
**Note**
The following steps require eksctl version `0.220.0` or later. To check your version, run `eksctl version`.
## Step 1: Create an IAM Capability Role
Create a trust policy file:
```
cat > argocd-trust-policy.json << 'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "capabilities.eks.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession"
]
}
]
}
EOF
```
Create the IAM role:
```
aws iam create-role \
--role-name ArgoCDCapabilityRole \
--assume-role-policy-document file://argocd-trust-policy.json
```
**Note**
For this basic setup, no additional IAM policies are needed. If you plan to use Secrets Manager for repository credentials or CodeConnections, you’ll need to add permissions to the role. For IAM policy examples and configuration guidance, see [Manage application secrets with AWS Secrets Manager](integration-secrets-manager.md) and [Connect to Git repositories with AWS CodeConnections](integration-codeconnections.md).
## Step 2: Get your AWS Identity Center configuration
Get your Identity Center instance ARN and user ID for RBAC configuration:
```
# Get your Identity Center instance ARN
aws sso-admin list-instances --query 'Instances[0].InstanceArn' --output text
# Get a user ID for admin access (replace 'your-username' with your Identity Center username)
aws identitystore list-users \
--identity-store-id $(aws sso-admin list-instances --query 'Instances[0].IdentityStoreId' --output text) \
--query 'Users[?UserName==`your-username`].UserId' --output text
```
Note these values - you’ll need them in the next step.
## Step 3: Create an eksctl configuration file
Create a file named `argocd-capability.yaml` with the following content. Replace the placeholder values with your cluster’s name, cluster’s region, IAM role ARN, Identity Center instance ARN, Identity Center region, and user ID:
```
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
name: my-cluster
region: cluster-region-code
capabilities:
- name: my-argocd
type: ARGOCD
roleArn: arn:aws:iam::[.replaceable]111122223333:role/ArgoCDCapabilityRole
deletePropagationPolicy: RETAIN
configuration:
argocd:
awsIdc:
idcInstanceArn: arn:aws:sso:::instance/ssoins-123abc
idcRegion: idc-region-code
rbacRoleMappings:
- role: ADMIN
identities:
- id: 38414300-1041-708a-01af-5422d6091e34
type: SSO_USER
```
**Note**
You can add multiple users or groups to the RBAC mappings. For groups, use `type: SSO_GROUP` and provide the group ID. Available roles are `ADMIN`, `EDITOR`, and `VIEWER`.
## Step 4: Create the Argo CD capability
Apply the configuration file:
```
eksctl create capability -f argocd-capability.yaml
```
The command returns immediately, but the capability takes some time to become active.
## Step 5: Verify the capability is active
Check the capability status. Replace *region-code* with the AWS Region that your cluster is in and replace *my-cluster* with the name of your cluster.
```
eksctl get capability \
--region region-code \
--cluster my-cluster \
--name my-argocd
```
The capability is ready when the status shows `ACTIVE`.
## Step 6: Verify custom resources are available
After the capability is active, verify that Argo CD custom resources are available in your cluster:
```
kubectl api-resources | grep argoproj.io
```
You should see `Application` and `ApplicationSet` resource types listed.
## Next steps
+ [Working with Argo CD](working-with-argocd.md) - Learn how to create and manage Argo CD Applications
+ [Argo CD considerations](argocd-considerations.md) - Configure SSO and multi-cluster access
+ [Working with capability resources](working-with-capabilities.md) - Manage your Argo CD capability resource
# Argo CD concepts
Argo CD implements GitOps by treating Git as the single source of truth for your application deployments. This topic walks through a practical example, then explains the core concepts you need to understand when working with the EKS Capability for Argo CD.
## Getting started with Argo CD
After creating the Argo CD capability (see [Create an Argo CD capability](create-argocd-capability.md)), you can start deploying applications. This example walks through registering a cluster and creating an Application.
### Step 1: Set up
**Register your cluster** (required)
Register the cluster where you want to deploy applications. For this example, we’ll register the same cluster where Argo CD is running (you can use the name `in-cluster` for compatibility with most Argo CD examples):
```
# Get your cluster ARN
CLUSTER_ARN=$(aws eks describe-cluster \
--name my-cluster \
--query 'cluster.arn' \
--output text)
# Register the cluster using Argo CD CLI
argocd cluster add $CLUSTER_ARN \
--aws-cluster-name $CLUSTER_ARN \
--name in-cluster \
--project default
```
**Note**
For information about configuring the Argo CD CLI to work with the Argo CD capability in EKS, see [Using the Argo CD CLI with the managed capability](argocd-comparison.md#argocd-cli-configuration).
Alternatively, register the cluster using a Kubernetes Secret (see [Register target clusters](argocd-register-clusters.md) for details).
**Configure repository access** (optional)
This example uses a public GitHub repository, so no repository configuration is required. For private repositories, configure access using AWS Secrets Manager, CodeConnections, or Kubernetes Secrets (see [Configure repository access](argocd-configure-repositories.md) for details).
For AWS services (ECR for Helm charts, CodeConnections, and CodeCommit), you can reference them directly in Application resources without creating a Repository. The Capability Role must have the required IAM permissions. See [Configure repository access](argocd-configure-repositories.md) for details.
### Step 2: Create an Application
Create this Application manifest in `my-app.yaml`:
```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: guestbook
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/argoproj/argocd-example-apps.git
targetRevision: HEAD
path: guestbook
destination:
name: in-cluster
namespace: guestbook
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
```
Apply the Application:
```
kubectl apply -f my-app.yaml
```
After applying this Application, Argo CD: 1. Syncs the application from Git to your cluster (initial deployment) 2. Monitors the Git repository for changes 3. Automatically syncs subsequent changes to your cluster 4. Detects and corrects any drift from the desired state 5. Provides health status and sync history in the UI
View the application status:
```
kubectl get application guestbook -n argocd
```
You can also view the application using the Argo CD CLI or the Argo CD UI (accessible from the EKS console under your cluster’s Capabilities tab).
**Note**
When using the Argo CD CLI with the managed capability, specify applications with the namespace prefix: `argocd app get argocd/guestbook`.
**Note**
Use the cluster name in `destination.name` (the name you used when registering the cluster). The managed capability does not support the local in-cluster default (`kubernetes.default.svc`).
## Core concepts
### GitOps principles and source types
Argo CD implements GitOps, where your application source is the single source of truth for deployments:
+ **Declarative** - Desired state is declared using YAML manifests, Helm charts, or Kustomize overlays
+ **Versioned** - Every change is tracked with complete audit trail
+ **Automated** - Argo CD continuously monitors sources and automatically syncs changes
+ **Self-healing** - Detects and corrects drift between desired and actual cluster state
**Supported source types**:
+ **Git repositories** - GitHub, GitLab, Bitbucket, CodeCommit (HTTPS, SSH, or CodeConnections)
+ **Helm registries** - HTTP registries (like `https://aws.github.io/eks-charts`) and OCI registries (like `public.ecr.aws`)
+ **OCI images** - Container images containing manifests or Helm charts (like `oci://registry-1.docker.io/user/my-app`)
This flexibility allows organizations to choose sources that meet their security and compliance requirements. For example, organizations that restrict Git access from clusters can use ECR for Helm charts or OCI images.
For more information, see [Application Sources](https://argo-cd.readthedocs.io/en/stable/user-guide/application-sources/) in the Argo CD documentation.
### Sync and reconciliation
Argo CD continuously monitors your sources and clusters to detect and correct differences:
1. Polls sources for changes (default: every 6 minutes)
1. Compares desired state with cluster state
1. Marks applications as `Synced` or `OutOfSync`
1. Syncs changes automatically (if configured) or waits for manual approval
1. Monitors resource health after sync
**Sync waves** control resource creation order using annotations:
```
metadata:
annotations:
argocd.argoproj.io/sync-wave: "0" # Default if not specified
```
Resources are applied in wave order (lower numbers first, including negative numbers like `-1`). Wave `0` is the default if not specified. This allows you to create dependencies like namespaces (wave `-1`) before deployments (wave `0`) before services (wave `1`).
**Self-healing** automatically reverts manual changes:
```
spec:
syncPolicy:
automated:
selfHeal: true
```
**Note**
The managed capability uses annotation-based resource tracking (not label-based) for better compatibility with Kubernetes conventions and other tools.
For detailed information about sync phases, hooks, and advanced patterns, see the [Argo CD sync documentation](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/).
### Application health
Argo CD monitors the health of all resources in your application:
**Health statuses**: \$1 **Healthy** - All resources running as expected \$1 **Progressing** - Resources being created or updated \$1 **Degraded** - Some resources not healthy (pods crashing, jobs failing) \$1 **Suspended** - Application intentionally paused \$1 **Missing** - Resources defined in Git not present in cluster
Argo CD has built-in health checks for common Kubernetes resources (Deployments, StatefulSets, Jobs, etc.) and supports custom health checks for CRDs.
Application health is determined by all its resources - if any resource is `Degraded`, the application is `Degraded`.
For more information, see [Resource Health](https://argo-cd.readthedocs.io/en/stable/operator-manual/health/) in the Argo CD documentation.
### Multi-cluster patterns
Argo CD supports two main deployment patterns:
**Hub-and-spoke** - Run Argo CD on a dedicated management cluster that deploys to multiple workload clusters: \$1 Centralized control and visibility \$1 Consistent policies across all clusters \$1 One Argo CD instance to manage \$1 Clear separation between control plane and workloads
**Per-cluster** - Run Argo CD on each cluster, managing only that cluster’s applications: \$1 Cluster separation (one failure doesn’t affect others) \$1 Simpler networking (no cross-cluster communication) \$1 Easier initial setup (no cluster registration)
Choose hub-and-spoke for platform teams managing many clusters, or per-cluster for independent teams or when clusters must be fully isolated.
For detailed multi-cluster configuration, see [Argo CD considerations](argocd-considerations.md).
### Projects
Projects provide logical grouping and access control for Applications:
+ **Source restrictions** - Limit which Git repositories can be used
+ **Destination restrictions** - Limit which clusters and namespaces can be targeted
+ **Resource restrictions** - Limit which Kubernetes resource types can be deployed
+ **RBAC integration** - Map projects to AWS Identity Center user and group IDs
Applications belong to a single project. If not specified, they use the `default` project, which has no restrictions by default. For production use, edit the `default` project to restrict access and create new projects with appropriate restrictions.
For project configuration and RBAC patterns, see [Configure Argo CD permissions](argocd-permissions.md).
### Sync options
Fine-tune sync behavior with common options:
+ `CreateNamespace=true` - Automatically create destination namespace
+ `ServerSideApply=true` - Use server-side apply for better conflict resolution
+ `SkipDryRunOnMissingResource=true` - Skip dry run when CRDs don’t exist yet (useful for kro instances)
```
spec:
syncPolicy:
syncOptions:
- CreateNamespace=true
- ServerSideApply=true
- SkipDryRunOnMissingResource=true
```
For a complete list of sync options, see the [Argo CD sync options documentation](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-options/).
## Next steps
+ [Configure repository access](argocd-configure-repositories.md) - Configure Git repository access
+ [Register target clusters](argocd-register-clusters.md) - Register target clusters for deployment
+ [Create Applications](argocd-create-application.md) - Create your first Application
+ [Argo CD considerations](argocd-considerations.md) - EKS-specific patterns, Identity Center integration, and multi-cluster configuration
+ [Argo CD Documentation](https://argo-cd.readthedocs.io/en/stable/) - Comprehensive Argo CD documentation including sync hooks, health checks, and advanced patterns
# Configure Argo CD permissions
The Argo CD managed capability integrates with AWS Identity Center for authentication and uses built-in RBAC roles for authorization. This topic explains how to configure permissions for users and teams.
## How permissions work with Argo CD
The Argo CD capability uses AWS Identity Center for authentication and provides three built-in RBAC roles for authorization.
When a user accesses Argo CD:
1. They authenticate using AWS Identity Center (which can federate to your corporate identity provider)
1. AWS Identity Center provides user and group information to Argo CD
1. Argo CD maps users and groups to RBAC roles based on your configuration
1. Users see only the applications and resources they have permission to access
## Built-in RBAC roles
The Argo CD capability provides three built-in roles that you map to AWS Identity Center users and groups. These are **globally scoped roles** that control access to Argo CD resources like projects, clusters, and repositories.
**Important**
Global roles control access to Argo CD itself, not to project-scoped resources like Applications. EDITOR and VIEWER users cannot see or manage Applications by default—they need project roles to access project-scoped resources. See [Project roles and project-scoped access](#project-roles) for details on granting access to Applications and other project-scoped resources.
**ADMIN**
Full access to all Argo CD resources and settings:
+ Create, update, and delete Applications and ApplicationSets in any project
+ Manage Argo CD configuration
+ Register and manage deployment target clusters
+ Configure repository access
+ Create and manage projects
+ View all application status and history
+ List and access all clusters and repositories
**EDITOR**
Can update projects and configure project roles, but cannot change global Argo CD settings:
+ Update existing projects (cannot create or delete projects)
+ Configure project roles and permissions
+ View GPG keys and certificates
+ Cannot change global Argo CD configuration
+ Cannot manage clusters or repositories directly
+ Cannot see or manage Applications without project roles
**VIEWER**
Read-only access to Argo CD resources:
+ View project configurations
+ List all projects (including projects the user is not assigned to)
+ View GPG keys and certificates
+ Cannot list clusters or repositories
+ Cannot make any changes
+ Cannot see or manage Applications without project roles
**Note**
To grant EDITOR or VIEWER users access to Applications, an ADMIN or EDITOR must create project roles that map Identity Center groups to specific permissions within a project.
## Project roles and project-scoped access
Global roles (ADMIN, EDITOR, VIEWER) control access to Argo CD itself. Project roles control access to resources and capabilities within a specific project, including:
+ **Resources**: Applications, ApplicationSets, repository credentials, cluster credentials
+ **Capabilities**: Log access, exec access to application pods
**Understanding the two-level permission model**:
+ **Global scope**: Built-in roles determine what users can do with projects, clusters, repositories, and Argo CD settings
+ **Project scope**: Project roles determine what users can do with resources and capabilities within a specific project
This means:
+ ADMIN users can access all project resources and capabilities without additional configuration
+ EDITOR and VIEWER users must be granted project roles to access project resources and capabilities
+ EDITOR users can create project roles to grant themselves and others access within projects they can update
**Example workflow**:
1. An ADMIN maps an Identity Center group to the EDITOR role globally
1. An ADMIN creates a project for a team
1. The EDITOR configures project roles within that project to grant team members access to project-scoped resources
1. Team members (who may have VIEWER global role) can now see and manage Applications in that project based on their project role permissions
For details on configuring project roles, see [Project-based access control](#_project_based_access_control).
## Configure role mappings
Map AWS Identity Center users and groups to Argo CD roles when creating or updating the capability.
**Example role mapping**:
```
{
"rbacRoleMapping": {
"ADMIN": ["AdminGroup", "alice@example.com"],
"EDITOR": ["DeveloperGroup", "DevOpsTeam"],
"VIEWER": ["ReadOnlyGroup", "bob@example.com"]
}
}
```
**Note**
Role names are case-sensitive and must be uppercase (ADMIN, EDITOR, VIEWER).
**Important**
EKS Capabilities integration with AWS Identity Center supports up to 1,000 identities per Argo CD capability. An identity can be a user or a group.
**Update role mappings**:
```
aws eks update-capability \
--region us-east-1 \
--cluster-name cluster \
--capability-name capname \
--endpoint "https://eks.ap-northeast-2.amazonaws.com" \
--role-arn "arn:aws:iam::[.replaceable]111122223333:role/[.replaceable]`EKSCapabilityRole`" \
--configuration '{
"argoCd": {
"rbacRoleMappings": {
"addOrUpdateRoleMappings": [
{
"role": "ADMIN",
"identities": [
{ "id": "686103e0-f051-7068-b225-e6392b959d9e", "type": "SSO_USER" }
]
}
]
}
}
}'
```
## Admin account usage
The admin account is designed for initial setup and administrative tasks like registering clusters and configuring repositories.
**When admin account is appropriate**:
+ Initial capability setup and configuration
+ Solo development or quick demonstrations
+ Administrative tasks (cluster registration, repository configuration, project creation)
**Best practices for admin account**:
+ Don’t commit account tokens to version control
+ Rotate tokens immediately if exposed
+ Limit account token usage to setup and administrative tasks
+ Set short expiration times (maximum 12 hours)
+ Only 5 account tokens can be created at any given time
**When to use project-based access instead**:
+ Shared development environments with multiple users
+ Any environment that resembles production
+ When you need audit trails of who performed actions
+ When you need to enforce resource restrictions or access boundaries
For production environments and multi-user scenarios, use project-based access control with dedicated RBAC roles mapped to AWS Identity Center groups.
## Project-based access control
Use Argo CD Projects (AppProject) to provide fine-grained access control and resource isolation for teams.
**Important**
Before assigning users or groups to project-specific roles, you must first map them to a global Argo CD role (ADMIN, EDITOR, or VIEWER) in the capability configuration. Users cannot access Argo CD without a global role mapping, even if they’re assigned to project roles.
Consider mapping users to the VIEWER role globally, then grant additional permissions through project-specific roles. This provides baseline access while allowing fine-grained control at the project level.
Projects provide:
+ **Source restrictions**: Limit which Git repositories can be used
+ **Destination restrictions**: Limit which clusters and namespaces can be targeted
+ **Resource restrictions**: Limit which Kubernetes resource types can be deployed
+ **RBAC integration**: Map projects to AWS Identity Center groups or Argo CD roles
**Example project for team isolation**:
```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: team-a
namespace: argocd
spec:
description: Team A applications
# Required: Specify which namespaces this project watches for Applications
sourceNamespaces:
- argocd
# Source restrictions
sourceRepos:
- https://github.com/myorg/team-a-apps
# Destination restrictions
destinations:
- namespace: team-a-*
server: arn:aws:eks:us-west-2:111122223333:cluster/production
# Resource restrictions
clusterResourceWhitelist:
- group: ''
kind: Namespace
namespaceResourceWhitelist:
- group: 'apps'
kind: Deployment
- group: ''
kind: Service
- group: ''
kind: ConfigMap
```
### Source namespaces
When using the EKS Argo CD capability, the `spec.sourceNamespaces` field is required in AppProject definitions. This field specifies which namespace can contain Applications or ApplicationSets that reference this project.
**Important**
The EKS Argo CD capability only supports a single namespace for Applications and ApplicationSets—the namespace you specified when creating the capability (typically `argocd`). This differs from open source Argo CD which supports multiple namespaces.
**AppProject configuration**
All AppProjects must include the capability’s configured namespace in `sourceNamespaces`:
```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: team-a-project
namespace: argocd
spec:
description: Applications for Team A
# Required: Specify the capability's configured namespace (configuration.argoCd.namespace)
sourceNamespaces:
- argocd # Must match your capability's namespace configuration
# Source repositories this project can deploy from
sourceRepos:
- 'https://github.com/my-org/team-a-*'
# Destination restrictions
destinations:
- namespace: 'team-a-*'
server: arn:aws:eks:us-west-2:111122223333:cluster/my-cluster
```
**Note**
If you omit the capability’s namespace from `sourceNamespaces`, Applications or ApplicationSets in that namespace cannot reference this project, resulting in deployment failures.
**Assign users to projects**:
Project roles grant EDITOR and VIEWER users access to project resources (Applications, ApplicationSets, repository and cluster credentials) and capabilities (logs, exec). Without project roles, these users cannot access these resources even if they have global role access.
ADMIN users have access to all Applications without needing project roles.
**Example: Granting Application access to team members**
```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: team-a
namespace: argocd
spec:
# ... project configuration ...
sourceNamespaces:
- argocd
# Project roles grant Application-level access
roles:
- name: developer
description: Team A developers - can manage Applications
policies:
- p, proj:team-a:developer, applications, *, team-a/*, allow
- p, proj:team-a:developer, clusters, get, *, allow # See cluster names in UI
groups:
- 686103e0-f051-7068-b225-e6392b959d9e # Identity Center group ID
- name: viewer
description: Team A viewers - read-only Application access
policies:
- p, proj:team-a:viewer, applications, get, team-a/*, allow
- p, proj:team-a:viewer, clusters, get, *, allow # See cluster names in UI
groups:
- 786203e0-f051-7068-b225-e6392b959d9f # Identity Center group ID
```
**Note**
Include `clusters, get, *, allow` in project roles to allow users to see cluster names in the UI. Without this permission, the destination cluster displays as "unknown".
**Understanding project role policies**:
The policy format is: `p, proj::, , ,