**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.

# Working with Argo CD
<a name="working-with-argocd"></a>

With Argo CD, you define applications in Git repositories and Argo CD automatically syncs them to your Kubernetes clusters. This enables declarative, version-controlled application deployment with automated drift detection.

## Prerequisites
<a name="_prerequisites"></a>

Before working with Argo CD, you need:
+ An EKS cluster with the Argo CD capability created (see [Create an Argo CD capability](create-argocd-capability.md))
+ A Git repository containing Kubernetes manifests
+  `kubectl` configured to communicate with your cluster

## Common tasks
<a name="_common_tasks"></a>

The following topics guide you through common Argo CD tasks:

 ** [Configure repository access](argocd-configure-repositories.md) ** - Configure Argo CD to access your Git repositories using AWS Secrets Manager, AWS CodeConnections, or Kubernetes Secrets.

 ** [Register target clusters](argocd-register-clusters.md) ** - Register target clusters where Argo CD will deploy applications.

 ** [Working with Argo CD Projects](argocd-projects.md) ** - Organize applications and enforce security boundaries using Projects for multi-tenant environments.

 ** [Create Applications](argocd-create-application.md) ** - Create Applications that deploy from Git repositories with automated or manual sync policies.

 ** [Use ApplicationSets](argocd-applicationsets.md) ** - Use ApplicationSets to deploy applications across multiple environments or clusters using templates and generators.

## Access the Argo CD UI
<a name="_access_the_argo_cd_ui"></a>

Access the Argo CD UI through the EKS console:

1. Open the Amazon EKS console

1. Select your cluster

1. Choose the **Capabilities** tab

1. Choose **Argo CD** 

1. Choose **Open Argo CD UI** 

The UI provides visual application topology, sync status and history, resource health and events, manual sync controls, and application management.

## Upstream documentation
<a name="_upstream_documentation"></a>

For detailed information about Argo CD features:
+  [Argo CD Documentation](https://argo-cd.readthedocs.io/) - Complete user guide
+  [Application Spec](https://argo-cd.readthedocs.io/en/stable/user-guide/application-specification/) - Full Application API reference
+  [ApplicationSet Guide](https://argo-cd.readthedocs.io/en/stable/user-guide/application-set/) - ApplicationSet patterns and examples
+  [Argo CD GitHub](https://github.com/argoproj/argo-cd) - Source code and examples

# Configure repository access
<a name="argocd-configure-repositories"></a>

Before deploying applications, configure Argo CD to access your Git repositories and Helm chart registries. Argo CD supports multiple authentication methods for GitHub, GitLab, Bitbucket, AWS CodeCommit, and AWS ECR.

**Note**  
For direct AWS service integrations (ECR Helm charts, CodeCommit repositories, and CodeConnections), you can reference them directly in Application resources without creating Repository configurations. The Capability Role must have the required IAM permissions. See [Configure Argo CD permissions](argocd-permissions.md) for details.

## Prerequisites
<a name="_prerequisites"></a>
+ An EKS cluster with the Argo CD capability created
+ Git repositories containing Kubernetes manifests
+  `kubectl` configured to communicate with your cluster

**Note**  
 AWS CodeConnections can connect to Git servers located in AWS Cloud or on-premises. For more information, see [AWS CodeConnections](https://docs.aws.amazon.com/codeconnections/latest/userguide/welcome.html).

## Authentication methods
<a name="_authentication_methods"></a>


| Method | Use Case | IAM Permissions Required | 
| --- | --- | --- | 
|   **Direct integration with AWS services**   | 
|  CodeCommit  |  Direct integration with AWS CodeCommit Git repositories. No Repository configuration needed.  |   `codecommit:GitPull`   | 
|  CodeConnections  |  Connect to GitHub, GitLab, or Bitbucket with managed authentication. Requires connection setup.  |   `codeconnections:UseConnection`   | 
|  ECR OCI Artifacts  |  Direct integration with AWS ECR for OCI Helm charts and manifest images. No Repository configuration needed.  |   `arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryPullOnly`   | 
|   **Repository configuration with credentials**   | 
|   AWS Secrets Manager (Username/Token)  |  Store personal access tokens or passwords. Enables credential rotation without Kubernetes access.  |   `arn:aws:iam::aws:policy/AWSSecretsManagerClientReadOnlyAccess`   | 
|   AWS Secrets Manager (SSH Key)  |  Use SSH key authentication. Enables credential rotation without Kubernetes access.  |   `arn:aws:iam::aws:policy/AWSSecretsManagerClientReadOnlyAccess`   | 
|   AWS Secrets Manager (GitHub App)  |  GitHub App authentication with private key. Enables credential rotation without Kubernetes access.  |   `arn:aws:iam::aws:policy/AWSSecretsManagerClientReadOnlyAccess`   | 
|  Kubernetes Secret  |  Standard Argo CD method using in-cluster secrets  |  None (permissions handled by EKS Access Entry with Kubernetes RBAC)  | 

## Direct access to AWS services
<a name="direct_access_to_shared_aws_services"></a>

For AWS services, you can reference them directly in Application resources without creating Repository configurations. The Capability Role must have the required IAM permissions.

### CodeCommit repositories
<a name="_codecommit_repositories"></a>

Reference CodeCommit repositories directly in Applications:

```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  source:
    repoURL: https://git-codecommit.region.amazonaws.com/v1/repos/repository-name
    targetRevision: main
    path: kubernetes/manifests
```

Required Capability Role permissions:

```
{
  "Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "codecommit:GitPull",
      "Resource": "arn:aws:codecommit:region:account-id:repository-name"
    }
  ]
}
```

### CodeConnections
<a name="_codeconnections"></a>

Reference GitHub, GitLab, or Bitbucket repositories through CodeConnections. The repository URL format is derived from the CodeConnections connection ARN.

The repository URL format is:

```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  source:
    repoURL: https://codeconnections.region.amazonaws.com/git-http/account-id/region/connection-id/owner/repository.git
    targetRevision: main
    path: kubernetes/manifests
```

Required Capability Role permissions:

```
{
  "Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "codeconnections:UseConnection",
      "Resource": "arn:aws:codeconnections:region:account-id:connection/connection-id"
    }
  ]
}
```

### ECR Helm charts
<a name="_ecr_helm_charts"></a>

ECR stores Helm charts as OCI artifacts. Argo CD supports two ways to reference them:

 **Helm format** (recommended for Helm charts):

```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app-helm
  namespace: argocd
spec:
  source:
    repoURL: account-id.dkr.ecr.region.amazonaws.com/repository-name
    targetRevision: chart-version
    chart: chart-name
    helm:
      valueFiles:
        - values.yaml
```

Note: Do not include the `oci://` prefix when using Helm format. Use the `chart` field to specify the chart name.

 **OCI format** (for OCI artifacts with Kubernetes manifests):

```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app-oci
  namespace: argocd
spec:
  source:
    repoURL: oci://account-id.dkr.ecr.region.amazonaws.com/repository-name
    targetRevision: artifact-version
    path: path-to-manifests
```

Note: Include the `oci://` prefix when using OCI format. Use the `path` field instead of `chart`.

Required Capability Role permissions - attach the managed policy:

```
arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryPullOnly
```

This policy includes the necessary ECR permissions: `ecr:GetAuthorizationToken`, `ecr:BatchGetImage`, and `ecr:GetDownloadUrlForLayer`.

## Using AWS Secrets Manager
<a name="using_shared_aws_secrets_manager"></a>

Store repository credentials in Secrets Manager and reference them in Argo CD Repository configurations. Using Secrets Manager enables automated credential rotation without requiring Kubernetes RBAC access—credentials can be rotated using IAM permissions to Secrets Manager, and Argo CD automatically reads the updated values.

**Note**  
For credential reuse across multiple repositories (for example, all repositories under a GitHub organization), use repository credential templates with `argocd.argoproj.io/secret-type: repo-creds`. This provides better UX than creating individual repository secrets. For more information, see [Repository Credentials](https://argo-cd.readthedocs.io/en/stable/operator-manual/argocd-repo-creds-yaml/) in the Argo CD documentation.

### Username and token authentication
<a name="_username_and_token_authentication"></a>

For HTTPS repositories with personal access tokens or passwords:

 **Create the secret in Secrets Manager**:

```
aws secretsmanager create-secret \
  --name argocd/my-repo \
  --description "GitHub credentials for Argo CD" \
  --secret-string '{"username":"your-username","token":"your-personal-access-token"}'
```

 **Optional TLS client certificate fields** (for private Git servers):

```
aws secretsmanager create-secret \
  --name argocd/my-private-repo \
  --secret-string '{
    "username":"your-username",
    "token":"your-token",
    "tlsClientCertData":"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi4uLgotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t",
    "tlsClientCertKey":"LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi4uLgotLS0tLUVORCBQUklWQVRFIEtFWS0tLS0t"
  }'
```

**Note**  
The `tlsClientCertData` and `tlsClientCertKey` values must be base64 encoded.

 **Create a Repository Secret referencing Secrets Manager**:

```
apiVersion: v1
kind: Secret
metadata:
  name: my-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://github.com/your-org/your-repo
  secretArn: arn:aws:secretsmanager:us-west-2:111122223333:secret:argocd/my-repo-AbCdEf
  project: default
```

### SSH key authentication
<a name="_ssh_key_authentication"></a>

For SSH-based Git access, store the private key as plaintext (not JSON):

 **Create the secret with SSH private key**:

```
aws secretsmanager create-secret \
  --name argocd/my-repo-ssh \
  --description "SSH key for Argo CD" \
  --secret-string "-----BEGIN OPENSSH PRIVATE KEY-----
b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAABlwAAAAdzc2gtcn
...
-----END OPENSSH PRIVATE KEY-----"
```

 **Create a Repository Secret for SSH**:

```
apiVersion: v1
kind: Secret
metadata:
  name: my-repo-ssh
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: git@github.com:your-org/your-repo.git
  secretArn: arn:aws:secretsmanager:us-west-2:111122223333:secret:argocd/my-repo-ssh-AbCdEf
  project: default
```

### GitHub App authentication
<a name="_github_app_authentication"></a>

For GitHub App authentication with a private key:

 **Create the secret with GitHub App credentials**:

```
aws secretsmanager create-secret \
  --name argocd/github-app \
  --description "GitHub App credentials for Argo CD" \
  --secret-string '{
    "githubAppPrivateKeySecret":"LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQouLi4KLS0tLS1FTkQgUlNBIFBSSVZBVEUgS0VZLS0tLS0=",
    "githubAppID":"123456",
    "githubAppInstallationID":"12345678"
  }'
```

**Note**  
The `githubAppPrivateKeySecret` value must be base64 encoded.

 **Optional field for GitHub Enterprise**:

```
aws secretsmanager create-secret \
  --name argocd/github-enterprise-app \
  --secret-string '{
    "githubAppPrivateKeySecret":"LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQouLi4KLS0tLS1FTkQgUlNBIFBSSVZBVEUgS0VZLS0tLS0=",
    "githubAppID":"123456",
    "githubAppInstallationID":"12345678",
    "githubAppEnterpriseBaseUrl":"https://github.example.com/api/v3"
  }'
```

 **Create a Repository Secret for GitHub App**:

```
apiVersion: v1
kind: Secret
metadata:
  name: my-repo-github-app
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://github.com/your-org/your-repo
  secretArn: arn:aws:secretsmanager:us-west-2:111122223333:secret:argocd/github-app-AbCdEf
  project: default
```

### Repository credential templates
<a name="_repository_credential_templates"></a>

For credential reuse across multiple repositories (for example, all repositories under a GitHub organization or user), use repository credential templates with `argocd.argoproj.io/secret-type: repo-creds`. This provides better UX than creating individual repository secrets for each repository.

 **Create a repository credential template**:

```
apiVersion: v1
kind: Secret
metadata:
  name: github-org-creds
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repo-creds
stringData:
  type: git
  url: https://github.com/your-org
  secretArn: arn:aws:secretsmanager:us-west-2:111122223333:secret:argocd/github-org-AbCdEf
```

This credential template applies to all repositories matching the URL prefix `https://github.com/your-org`. You can then reference any repository under this organization in Applications without creating additional secrets.

For more information, see [Repository Credentials](https://argo-cd.readthedocs.io/en/stable/operator-manual/argocd-repo-creds-yaml/) in the Argo CD documentation.

**Important**  
Ensure your IAM Capability Role has the managed policy `arn:aws:iam::aws:policy/AWSSecretsManagerClientReadOnlyAccess` attached, or equivalent permissions including `secretsmanager:GetSecretValue` and KMS decrypt permissions. See [Argo CD considerations](argocd-considerations.md) for IAM policy configuration.

## Using AWS CodeConnections
<a name="using_shared_aws_codeconnections"></a>

For CodeConnections integration, see [Connect to Git repositories with AWS CodeConnections](integration-codeconnections.md).

CodeConnections provides managed authentication for GitHub, GitLab, and Bitbucket without storing credentials.

## Using Kubernetes Secrets
<a name="_using_kubernetes_secrets"></a>

Store credentials directly in Kubernetes using the standard Argo CD method.

 **For HTTPS with personal access token**:

```
apiVersion: v1
kind: Secret
metadata:
  name: my-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://github.com/your-org/your-repo
  username: your-username
  password: your-personal-access-token
```

 **For SSH**:

```
apiVersion: v1
kind: Secret
metadata:
  name: my-repo-ssh
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: git@github.com:your-org/your-repo.git
  sshPrivateKey: |
    -----BEGIN OPENSSH PRIVATE KEY-----
    ... your private key ...
    -----END OPENSSH PRIVATE KEY-----
```

## CodeCommit repositories
<a name="_codecommit_repositories_2"></a>

For AWS CodeCommit, grant your IAM Capability Role CodeCommit permissions (`codecommit:GitPull`).

Configure the repository:

```
apiVersion: v1
kind: Secret
metadata:
  name: codecommit-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://git-codecommit.us-west-2.amazonaws.com/v1/repos/my-repo
  project: default
```

For detailed IAM policy configuration, see [Argo CD considerations](argocd-considerations.md).

## Verify repository connection
<a name="_verify_repository_connection"></a>

Check connection status through the Argo CD UI under Settings → Repositories. The UI shows connection status and any authentication errors.

Repository Secrets do not include status information.

## Additional resources
<a name="_additional_resources"></a>
+  [Register target clusters](argocd-register-clusters.md) - Register target clusters for deployments
+  [Create Applications](argocd-create-application.md) - Create your first Application
+  [Argo CD considerations](argocd-considerations.md) - IAM permissions and security configuration
+  [Private Repositories](https://argo-cd.readthedocs.io/en/stable/user-guide/private-repositories/) - Upstream repository configuration reference

# Register target clusters
<a name="argocd-register-clusters"></a>

Register clusters to enable Argo CD to deploy applications to them. You can register the same cluster where Argo CD is running (local cluster) or remote clusters in different accounts or regions. Once a cluster is registered, it will remain in an Unknown connection state until you create an application within that cluster. To create an Argo CD application after your cluster is registered, see [Create Applications](argocd-create-application.md).

## Prerequisites
<a name="_prerequisites"></a>
+ An EKS cluster with the Argo CD capability created
+  `kubectl` configured to communicate with your cluster
+ For remote clusters: appropriate IAM permissions and access entries

## Register the local cluster
<a name="_register_the_local_cluster"></a>

To deploy applications to the same cluster where Argo CD is running, register it as a deployment target.

**Important**  
The Argo CD capability does not automatically register the local cluster. You must explicitly register it to deploy applications to the same cluster. You can use the cluster name `in-cluster` for compatibility with most Argo CD examples online.

**Note**  
An EKS Access Entry is automatically created for the local cluster with the Argo CD Capability Role, but no Kubernetes RBAC permissions are granted by default. This follows the principle of least privilege—you must explicitly configure the permissions Argo CD needs based on your use case. For example, if you only use this cluster as an Argo CD hub to manage remote clusters, it doesn’t need any local deployment permissions. See the Access Entry RBAC requirements section below for configuration options.

 **Using the Argo CD CLI**:

```
argocd cluster add <cluster-context-name> \
  --aws-cluster-name arn:aws:eks:us-west-2:111122223333:cluster/my-cluster \
  --name local-cluster
```

 **Using a Kubernetes Secret**:

```
apiVersion: v1
kind: Secret
metadata:
  name: local-cluster
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: cluster
stringData:
  name: local-cluster
  server: arn:aws:eks:us-west-2:111122223333:cluster/my-cluster
  project: default
```

Apply the configuration:

```
kubectl apply -f local-cluster.yaml
```

**Note**  
Use the EKS cluster ARN in the `server` field, not the Kubernetes API server URL. The managed capability requires ARNs to identify clusters. The default `kubernetes.default.svc` is not supported.

## Register remote clusters
<a name="_register_remote_clusters"></a>

To deploy to remote clusters:

 **Step 1: Create the access entry on the remote cluster** 

Replace *region-code* with the AWS Region that your remote cluster is in, replace *remote-cluster* with the name of your remote cluster, and replace the ARN with your Argo CD capability role ARN.

```
aws eks create-access-entry \
  --region region-code \
  --cluster-name remote-cluster \
  --principal-arn arn:aws:iam::[.replaceable]111122223333:role/ArgoCDCapabilityRole \
  --type STANDARD
```

 **Step 2: Associate an access policy with Kubernetes RBAC permissions** 

The Access Entry requires Kubernetes RBAC permissions for Argo CD to deploy applications. For getting started quickly, you can use the `AmazonEKSClusterAdminPolicy`:

```
aws eks associate-access-policy \
  --region region-code \
  --cluster-name remote-cluster \
  --principal-arn arn:aws:iam::[.replaceable]111122223333:role/ArgoCDCapabilityRole \
  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \
  --access-scope type=cluster
```

**Important**  
The `AmazonEKSClusterAdminPolicy` provides full cluster-admin access (equivalent to `system:masters`). This is convenient for getting started but should not be used in production. For production environments, use more restrictive permissions by associating the Access Entry with custom Kubernetes groups and creating appropriate Role or ClusterRole bindings. See the production setup section below for least privilege configuration.

 **Step 3: Register the cluster in Argo CD** 

 **Using the Argo CD CLI**:

```
argocd cluster add <cluster-context-name> \
  --aws-cluster-name arn:aws:eks:us-west-2:111122223333:cluster/remote-cluster \
  --name remote-cluster
```

 **Using a Kubernetes Secret**:

```
apiVersion: v1
kind: Secret
metadata:
  name: remote-cluster
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: cluster
stringData:
  name: remote-cluster
  server: arn:aws:eks:us-west-2:111122223333:cluster/remote-cluster
  project: default
```

Apply the configuration:

```
kubectl apply -f remote-cluster.yaml
```

## Cross-account clusters
<a name="_cross_account_clusters"></a>

To deploy to clusters in different AWS accounts:

1. In the target account, create an Access Entry on the target EKS cluster using the Argo CD IAM Capability Role ARN from the source account as the principal

1. Associate an access policy with appropriate Kubernetes RBAC permissions

1. Register the cluster in Argo CD using its EKS cluster ARN

No additional IAM role creation or trust policy configuration is required—EKS Access Entries handle cross-account access.

The cluster ARN format includes the region, so cross-region deployments use the same process as same-region deployments.

## Verify cluster registration
<a name="_verify_cluster_registration"></a>

View registered clusters:

```
kubectl get secrets -n argocd -l argocd.argoproj.io/secret-type=cluster
```

Or check cluster status in the Argo CD UI under Settings → Clusters.

## Private clusters
<a name="_private_clusters"></a>

The Argo CD capability 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.

Simply register the private cluster using its ARN—no additional networking setup required.

## Access Entry RBAC requirements
<a name="_access_entry_rbac_requirements"></a>

When you create an Argo CD capability, an EKS Access Entry is automatically created for the Capability Role, but no Kubernetes RBAC permissions are granted by default. This intentional design follows the principle of least privilege—different use cases require different permissions.

For example: \$1 If you use the cluster only as an Argo CD hub to manage remote clusters, it doesn’t need local deployment permissions \$1 If you deploy applications locally, it needs read access cluster-wide and write access to specific namespaces \$1 If you need to create CRDs, it requires additional cluster-admin permissions

You must explicitly configure the permissions Argo CD needs based on your requirements.

### Minimum permissions for Argo CD
<a name="_minimum_permissions_for_argo_cd"></a>

Argo CD needs two types of permissions to function without errors:

 **Read permissions (cluster-wide)**: Argo CD must be able to read all resource types and Custom Resource Definitions (CRDs) across the cluster for:
+ Resource discovery and health checks
+ Detecting drift between desired and actual state
+ Validating resources before deployment

 **Write permissions (namespace-specific)**: Argo CD needs create, update, and delete permissions for resources defined in Applications:
+ Deploy application workloads (Deployments, Services, ConfigMaps, etc.)
+ Apply Custom Resources (CRDs specific to your applications)
+ Manage application lifecycle

### Quick setup
<a name="_quick_setup"></a>

For getting started quickly, testing, or development environments, use `AmazonEKSClusterAdminPolicy`:

```
aws eks associate-access-policy \
  --region region-code \
  --cluster-name my-cluster \
  --principal-arn arn:aws:iam::[.replaceable]111122223333:role/ArgoCDCapabilityRole \
  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \
  --access-scope type=cluster
```

**Important**  
The `AmazonEKSClusterAdminPolicy` provides full cluster-admin access (equivalent to `system:masters`), including the ability to create CRDs, modify cluster-wide resources, and deploy to any namespace. This is convenient for development and POCs but should not be used in production. For production, use the least privilege setup below.

### Production setup with least privilege
<a name="_production_setup_with_least_privilege"></a>

For production environments, create custom Kubernetes RBAC that grants:
+ Cluster-wide read access to all resources (for discovery and health checks)
+ Namespace-specific write access (for deployments)

 **Step 1: Associate Access Entry with a custom Kubernetes group** 

```
aws eks associate-access-policy \
  --region region-code \
  --cluster-name my-cluster \
  --principal-arn arn:aws:iam::[.replaceable]111122223333:role/ArgoCDCapabilityRole \
  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSEditPolicy \
  --access-scope type=namespace,namespaces=app-namespace
```

 **Step 2: Create ClusterRole for read access** 

```
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: argocd-read-all
rules:
# Read access to all resources for discovery and health checks
- apiGroups: ["*"]
  resources: ["*"]
  verbs: ["get", "list", "watch"]
```

 **Step 3: Create Role for write access to application namespaces** 

```
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: argocd-deploy
  namespace: app-namespace
rules:
# Full access to deploy application resources
- apiGroups: ["*"]
  resources: ["*"]
  verbs: ["*"]
```

 **Step 4: Bind roles to the Kubernetes group** 

```
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: argocd-read-all
subjects:
- kind: Group
  name: eks-access-entry:arn:aws:iam::111122223333:role/ArgoCDCapabilityRole
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: argocd-read-all
  apiGroup: rbac.authorization.k8s.io
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: argocd-deploy
  namespace: app-namespace
subjects:
- kind: Group
  name: eks-access-entry:arn:aws:iam::111122223333:role/ArgoCDCapabilityRole
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: argocd-deploy
  apiGroup: rbac.authorization.k8s.io
```

**Note**  
The group name format for Access Entries is `eks-access-entry:` followed by the principal ARN. Repeat the RoleBinding for each namespace where Argo CD should deploy applications.

**Important**  
Argo CD must be able to read all resource types across the cluster for health checks and discovery, even if it only deploys to specific namespaces. Without cluster-wide read access, Argo CD will show errors when checking application health.

## Restrict cluster access with Projects
<a name="_restrict_cluster_access_with_projects"></a>

Use Projects to control which clusters and namespaces Applications can deploy to by configuring the allowed target clusters and namespaces in `spec.destinations`:

```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: production
  namespace: argocd
spec:
  destinations:
  - server: arn:aws:eks:us-west-2:111122223333:cluster/prod-cluster
    namespace: '*'
  - server: arn:aws:eks:eu-west-1:111122223333:cluster/prod-eu-cluster
    namespace: '*'
  sourceRepos:
  - 'https://github.com/example/production-apps'
```

For details, see [Working with Argo CD Projects](argocd-projects.md).

## Additional resources
<a name="_additional_resources"></a>
+  [Working with Argo CD Projects](argocd-projects.md) - Organize applications and enforce security boundaries
+  [Create Applications](argocd-create-application.md) - Deploy your first application
+  [Use ApplicationSets](argocd-applicationsets.md) - Deploy to multiple clusters with ApplicationSets
+  [Argo CD considerations](argocd-considerations.md) - Multi-cluster patterns and cross-account setup
+  [Declarative Cluster Setup](https://argo-cd.readthedocs.io/en/stable/operator-manual/declarative-setup/#clusters) - Upstream cluster configuration reference

# Working with Argo CD Projects
<a name="argocd-projects"></a>

Argo CD Projects (AppProject) provide logical grouping and access control for Applications. Projects define which Git repositories, target clusters, and namespaces Applications can use, enabling multi-tenancy and security boundaries in shared Argo CD instances.

## When to use Projects
<a name="_when_to_use_projects"></a>

Use Projects to:
+ Separate applications by team, environment, or business unit
+ Restrict which repositories teams can deploy from
+ Limit which clusters and namespaces teams can deploy to
+ Enforce resource quotas and allowed resource types
+ Provide self-service application deployment with guardrails

## Default Project
<a name="_default_project"></a>

Every Argo CD capability includes a `default` project that allows access to all repositories, clusters, and namespaces. While useful for initial testing, create dedicated projects with explicit restrictions for production use.

For details on the default project configuration and how to restrict it, see [The Default Project](https://argo-cd.readthedocs.io/en/stable/user-guide/projects/#the-default-project) in the Argo CD documentation.

## Create a Project
<a name="_create_a_project"></a>

Create a Project by applying an `AppProject` resource to your cluster.

 **Example: Team-specific Project** 

```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-a
  namespace: argocd
spec:
  description: Applications for Team A

  # Source repositories this project can deploy from
  sourceRepos:
    - 'https://github.com/my-org/team-a-*'
    - 'https://github.com/my-org/shared-libs'


  # Source namespaces (required for EKS capability)
  sourceNamespaces:
    - argocd
    - team-a-dev
    - team-a-prod

  # Destination clusters and namespaces
  destinations:
    - name: dev-cluster
      namespace: team-a-dev
    - name: prod-cluster
      namespace: team-a-prod

  # Allowed resource types
  clusterResourceWhitelist:
    - group: ''
      kind: Namespace

  namespaceResourceWhitelist:
    - group: 'apps'
      kind: Deployment
    - group: ''
      kind: Service
    - group: ''
      kind: ConfigMap
```

Apply the Project:

```
kubectl apply -f team-a-project.yaml
```

## Project configuration
<a name="_project_configuration"></a>

### Source repositories
<a name="_source_repositories"></a>

Control which Git repositories Applications in this project can use:

```
spec:
  sourceRepos:
    - 'https://github.com/my-org/app-*'  # Wildcard pattern
    - 'https://github.com/my-org/infra'  # Specific repo
```

You can use wildcards and negation patterns (`!` prefix) to allow or deny specific repositories. For details, see [Managing Projects](https://argo-cd.readthedocs.io/en/stable/user-guide/projects/#managing-projects) in the Argo CD documentation.

### Source namespaces
<a name="_source_namespaces"></a>

When using the EKS Argo CD capability, the `spec.sourceNamespaces` field is **required** in your custom AppProject definition. This field specifies which namespaces can contain Applications or ApplicationSets that reference this project:

**Important**  
This is a required field for EKS Argo CD capability, which differs from OSS Argo CD where this field is optional.

#### Default AppProject behavior
<a name="_default_appproject_behavior"></a>

The `default` AppProject automatically includes the `argocd` namespace in `sourceNamespaces`. If you need to create Applications or ApplicationSets in additional namespaces, modify the `sourceNamespaces` field to add those namespaces:

```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: default
  namespace: argocd
spec:
  sourceNamespaces:
    - argocd           # Already included by default
    - team-a-apps      # Add additional namespaces as needed
    - team-b-apps
```

#### Custom AppProject configuration
<a name="_custom_appproject_configuration"></a>

When creating a custom AppProject, you must manually include the `argocd` system namespace and any other namespaces where you plan to create Applications or ApplicationSets:

```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-a-project
  namespace: argocd
spec:
  description: Applications for Team A

  # Required: Manually specify all namespaces
  sourceNamespaces:
    - argocd           # ArgoCD system namespace (required)
    - team-a-dev       # Custom namespace for dev Applications
    - team-a-prod      # Custom namespace for prod Applications

  # Source repositories this project can deploy from
  sourceRepos:
    - 'https://github.com/my-org/team-a-*'

  # Destination restrictions
  destinations:
    - namespace: 'team-a-*'
      server: https://kubernetes.default.svc
```

**Note**  
If you omit a namespace from `sourceNamespaces`, Applications or ApplicationSets created in that namespace will not be able to reference this project, resulting in deployment failures.

### Destination restrictions
<a name="_destination_restrictions"></a>

Limit where Applications can deploy:

```
spec:
  destinations:
    - name: prod-cluster  # Specific cluster by name
      namespace: production
    - name: '*'  # Any cluster
      namespace: team-a-*  # Namespace pattern
```

**Important**  
Use specific cluster names and namespace patterns rather than wildcards for production Projects. This prevents accidental deployments to unauthorized clusters or namespaces.

You can use wildcards and negation patterns to control destinations. For details, see [Managing Projects](https://argo-cd.readthedocs.io/en/stable/user-guide/projects/#managing-projects) in the Argo CD documentation.

### Resource restrictions
<a name="_resource_restrictions"></a>

Control which Kubernetes resource types can be deployed:

 **Cluster-scoped resources**:

```
spec:
  clusterResourceWhitelist:
    - group: ''
      kind: Namespace
    - group: 'rbac.authorization.k8s.io'
      kind: Role
```

 **Namespace-scoped resources**:

```
spec:
  namespaceResourceWhitelist:
    - group: 'apps'
      kind: Deployment
    - group: ''
      kind: Service
    - group: ''
      kind: ConfigMap
    - group: 's3.services.k8s.aws'
      kind: Bucket
```

Use blacklists to deny specific resources:

```
spec:
  namespaceResourceBlacklist:
    - group: ''
      kind: Secret  # Prevent direct Secret creation
```

## Assign Applications to Projects
<a name="_assign_applications_to_projects"></a>

When creating an Application, specify the project in the `spec.project` field:

```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: team-a  # Assign to team-a project
  source:
    repoURL: https://github.com/my-org/my-app
    path: manifests
  destination:
    name: prod-cluster
    namespace: team-a-prod
```

Applications without a specified project use the `default` project.

## Project roles and RBAC
<a name="_project_roles_and_rbac"></a>

Projects can define custom roles for fine-grained access control. Map project roles to AWS Identity Center users and groups in your capability configuration to control who can sync, update, or delete applications.

 **Example: Project with developer and admin roles** 

```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-a
  namespace: argocd
spec:
  sourceRepos:
    - '*'
  destinations:
    - name: '*'
      namespace: 'team-a-*'

  roles:
    - name: developer
      description: Developers can sync applications
      policies:
        - p, proj:team-a:developer, applications, sync, team-a/*, allow
        - p, proj:team-a:developer, applications, get, team-a/*, allow
      groups:
        - team-a-developers

    - name: admin
      description: Admins have full access
      policies:
        - p, proj:team-a:admin, applications, *, team-a/*, allow
      groups:
        - team-a-admins
```

For details on project roles, JWT tokens for CI/CD pipelines, and RBAC configuration, see [Project Roles](https://argo-cd.readthedocs.io/en/stable/user-guide/projects/#project-roles) in the Argo CD documentation.

## Common patterns
<a name="_common_patterns"></a>

### Environment-based Projects
<a name="_environment_based_projects"></a>

Create separate projects for each environment:

```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: production
  namespace: argocd
spec:
  sourceRepos:
    - 'https://github.com/my-org/*'
  destinations:
    - name: prod-cluster
      namespace: '*'
  # Strict resource controls for production
  clusterResourceWhitelist: []
  namespaceResourceWhitelist:
    - group: 'apps'
      kind: Deployment
    - group: ''
      kind: Service
```

### Team-based Projects
<a name="_team_based_projects"></a>

Isolate teams with dedicated projects:

```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: platform-team
  namespace: argocd
spec:
  sourceRepos:
    - 'https://github.com/my-org/platform-*'
  destinations:
    - name: '*'
      namespace: 'platform-*'
  # Platform team can manage cluster resources
  clusterResourceWhitelist:
    - group: '*'
      kind: '*'
```

### Multi-cluster Projects
<a name="_multi_cluster_projects"></a>

Deploy to multiple clusters with consistent policies:

```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: global-app
  namespace: argocd
spec:
  sourceRepos:
    - 'https://github.com/my-org/global-app'
  destinations:
    - name: us-west-cluster
      namespace: app
    - name: eu-west-cluster
      namespace: app
    - name: ap-south-cluster
      namespace: app
```

## Best practices
<a name="_best_practices"></a>

 **Start with restrictive Projects**: Begin with narrow permissions and expand as needed rather than starting with broad access.

 **Use namespace patterns**: Leverage wildcards in namespace restrictions (like `team-a-*`) to allow flexibility while maintaining boundaries.

 **Separate production Projects**: Use dedicated Projects for production with stricter controls and manual sync policies.

 **Document Project purposes**: Use the `description` field to explain what each Project is for and who should use it.

 **Review Project permissions regularly**: Audit Projects periodically to ensure restrictions still align with team needs and security requirements.

## Additional resources
<a name="_additional_resources"></a>
+  [Configure Argo CD permissions](argocd-permissions.md) - Configure RBAC and Identity Center integration
+  [Create Applications](argocd-create-application.md) - Create Applications within Projects
+  [Use ApplicationSets](argocd-applicationsets.md) - Use ApplicationSets with Projects for multi-cluster deployments
+  [Argo CD Projects Documentation](https://argo-cd.readthedocs.io/en/stable/user-guide/projects/) - Complete upstream reference

# Create Applications
<a name="argocd-create-application"></a>

Applications represent deployments in target clusters. Each Application defines a source (Git repository) and destination (cluster and namespace). When applied, Argo CD will create the resources specified by manifests in the Git repository to the namespace in the cluster. Applications often specify workload deployments, but they can manage any Kubernetes resources available in the destination cluster.

## Prerequisites
<a name="_prerequisites"></a>
+ An EKS cluster with the Argo CD capability created
+ Repository access configured (see [Configure repository access](argocd-configure-repositories.md))
+ Target cluster registered (see [Register target clusters](argocd-register-clusters.md))
+  `kubectl` configured to communicate with your cluster

## Create a basic Application
<a name="_create_a_basic_application"></a>

Define an Application that deploys from a Git repository:

```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps
    targetRevision: HEAD
    path: guestbook
  destination:
    name: in-cluster
    namespace: default
```

**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.

Apply the Application:

```
kubectl apply -f application.yaml
```

View the Application status:

```
kubectl get application guestbook -n argocd
```

## Source configuration
<a name="_source_configuration"></a>

 **Git repository**:

```
spec:
  source:
    repoURL: https://github.com/example/my-app
    targetRevision: main
    path: kubernetes/manifests
```

 **Specific Git tag or commit**:

```
spec:
  source:
    targetRevision: v1.2.0  # or commit SHA
```

 **Helm chart**:

```
spec:
  source:
    repoURL: https://github.com/example/helm-charts
    targetRevision: main
    path: charts/my-app
    helm:
      valueFiles:
      - values.yaml
      parameters:
      - name: image.tag
        value: v1.2.0
```

 **Helm chart with values from external Git repository** (multi-source pattern):

```
spec:
  sources:
  - repoURL: https://github.com/example/helm-charts
    targetRevision: main
    path: charts/my-app
    helm:
      valueFiles:
      - $values/environments/production/values.yaml
  - repoURL: https://github.com/example/config-repo
    targetRevision: main
    ref: values
```

For more information, see [Helm Value Files from External Git Repository](https://argo-cd.readthedocs.io/en/stable/user-guide/multiple_sources/#helm-value-files-from-external-git-repository) in the Argo CD documentation.

 **Helm chart from ECR**:

```
spec:
  source:
    repoURL: oci://account-id.dkr.ecr.region.amazonaws.com/repository-name
    targetRevision: chart-version
    chart: chart-name
```

If the Capability Role has the required ECR permissions, the repository is used directly and no Repository configuration is required. See [Configure repository access](argocd-configure-repositories.md) for details.

 **Git repository from CodeCommit**:

```
spec:
  source:
    repoURL: https://git-codecommit.region.amazonaws.com/v1/repos/repository-name
    targetRevision: main
    path: kubernetes/manifests
```

If the Capability Role has the required CodeCommit permissions, the repository is used directly and no Repository configuration is required. See [Configure repository access](argocd-configure-repositories.md) for details.

 **Git repository from CodeConnections**:

```
spec:
  source:
    repoURL: https://codeconnections.region.amazonaws.com/git-http/account-id/region/connection-id/owner/repository.git
    targetRevision: main
    path: kubernetes/manifests
```

The repository URL format is derived from the CodeConnections connection ARN. If the Capability Role has the required CodeConnections permissions and a connection is configured, the repository is used directly and no Repository configuration is required. See [Configure repository access](argocd-configure-repositories.md) for details.

 **Kustomize**:

```
spec:
  source:
    repoURL: https://github.com/example/kustomize-app
    targetRevision: main
    path: overlays/production
    kustomize:
      namePrefix: prod-
```

## Sync policies
<a name="_sync_policies"></a>

Control how Argo CD syncs applications.

 **Manual sync (default)**:

Applications require manual approval to sync:

```
spec:
  syncPolicy: {}  # No automated sync
```

Manually trigger sync:

```
kubectl patch application guestbook -n argocd \
  --type merge \
  --patch '{"operation": {"initiatedBy": {"username": "admin"}, "sync": {}}}'
```

 **Automatic sync**:

Applications automatically sync when Git changes are detected:

```
spec:
  syncPolicy:
    automated: {}
```

 **Self-healing**:

Automatically revert manual changes to the cluster:

```
spec:
  syncPolicy:
    automated:
      selfHeal: true
```

When enabled, Argo CD reverts any manual changes made directly to the cluster, ensuring Git remains the source of truth.

 **Pruning**:

Automatically delete resources removed from Git:

```
spec:
  syncPolicy:
    automated:
      prune: true
```

**Warning**  
Pruning will delete resources from your cluster. Use with caution in production environments.

 **Combined automated sync**:

```
spec:
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true
```

 **Retry configuration**:

Configure retry behavior for failed syncs:

```
spec:
  syncPolicy:
    retry:
      limit: 5  # Number of failed sync attempts; unlimited if less than 0
      backoff:
        duration: 5s  # Amount to back off (default unit: seconds, also supports "2m", "1h")
        factor: 2  # Factor to multiply the base duration after each failed retry
        maxDuration: 3m  # Maximum amount of time allowed for the backoff strategy
```

This is particularly useful for resources that depend on CRDs being created first, or when working with kro instances where the CRD may not be immediately available.

## Sync options
<a name="_sync_options"></a>

Additional sync configuration:

 **Create namespace if it doesn’t exist**:

```
spec:
  syncPolicy:
    syncOptions:
    - CreateNamespace=true
```

 **Skip dry run for missing resources**:

Useful when applying resources that depend on CRDs that don’t exist yet (like kro instances):

```
spec:
  syncPolicy:
    syncOptions:
    - SkipDryRunOnMissingResource=true
```

This can also be applied to specific resources using a label on the resource itself.

 **Validate resources before applying**:

```
spec:
  syncPolicy:
    syncOptions:
    - Validate=true
```

 **Apply out of sync only**:

```
spec:
  syncPolicy:
    syncOptions:
    - ApplyOutOfSyncOnly=true
```

## Advanced sync features
<a name="_advanced_sync_features"></a>

Argo CD supports advanced sync features for complex deployments:
+  **Sync waves** - Control resource creation order with `argocd.argoproj.io/sync-wave` annotations
+  **Sync hooks** - Run jobs before or after sync with `argocd.argoproj.io/hook` annotations (PreSync, PostSync, SyncFail)
+  **Resource health assessment** - Custom health checks for application-specific resources

For details, see [Sync Waves](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/) and [Resource Hooks](https://argo-cd.readthedocs.io/en/stable/user-guide/resource_hooks/) in the Argo CD documentation.

## Ignore differences
<a name="_ignore_differences"></a>

Prevent Argo CD from syncing specific fields that are managed by other controllers (like HPA managing replicas):

```
spec:
  ignoreDifferences:
  - group: apps
    kind: Deployment
    jsonPointers:
    - /spec/replicas
```

For details on ignore patterns and field exclusions, see [Diffing Customization](https://argo-cd.readthedocs.io/en/stable/user-guide/diffing/) in the Argo CD documentation.

## Multi-environment deployment
<a name="_multi_environment_deployment"></a>

Deploy the same application to multiple environments:

 **Development**:

```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app-dev
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/my-app
    targetRevision: develop
    path: overlays/development
  destination:
    name: dev-cluster
    namespace: my-app
```

 **Production**:

```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app-prod
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/my-app
    targetRevision: main
    path: overlays/production
  destination:
    name: prod-cluster
    namespace: my-app
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
```

## Monitor and manage Applications
<a name="_monitor_and_manage_applications"></a>

 **View Application status**:

```
kubectl get application my-app -n argocd
```

 **Access the Argo CD UI**:

Open the Argo CD UI through the EKS console to view application topology, sync status, resource health, and deployment history. See [Working with Argo CD](working-with-argocd.md) for UI access instructions.

 **Rollback Applications**:

Rollback to a previous revision using the Argo CD UI, the Argo CD CLI, or by updating the `targetRevision` in the Application spec to a previous Git commit or tag.

Using the Argo CD CLI:

```
argocd app rollback argocd/my-app <revision-id>
```

**Note**  
When using the Argo CD CLI with the managed capability, specify applications with the namespace prefix: `namespace/appname`.

For more information, see [argocd app rollback](https://argo-cd.readthedocs.io/en/stable/user-guide/commands/argocd_app_rollback/) in the Argo CD documentation.

## Additional resources
<a name="_additional_resources"></a>
+  [Working with Argo CD Projects](argocd-projects.md) - Organize applications with Projects for multi-tenant environments
+  [Use ApplicationSets](argocd-applicationsets.md) - Deploy to multiple clusters with templates
+  [Application Specification](https://argo-cd.readthedocs.io/en/stable/user-guide/application-specification/) - Complete Application API reference
+  [Sync Options](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-options/) - Advanced sync configuration

# Use ApplicationSets
<a name="argocd-applicationsets"></a>

ApplicationSets generate multiple Applications from templates, enabling you to deploy the same application across multiple clusters, environments, or namespaces with a single resource definition.

## Prerequisites
<a name="_prerequisites"></a>
+ An EKS cluster with the Argo CD capability created
+ Repository access configured (see [Configure repository access](argocd-configure-repositories.md))
+  `kubectl` configured to communicate with your cluster

**Note**  
Multiple target clusters are not required for ApplicationSets. You can use generators other than the cluster generator (like list, git, or matrix generators) to deploy applications without remote clusters.

## How ApplicationSets work
<a name="_how_applicationsets_work"></a>

ApplicationSets use generators to produce parameters, then apply those parameters to an Application template. Each set of generated parameters creates one Application.

Common generators for EKS deployments:
+  **List generator** - Explicitly define clusters and parameters for each environment
+  **Cluster generator** - Automatically deploy to all registered clusters
+  **Git generator** - Generate Applications from repository structure
+  **Matrix generator** - Combine generators for multi-dimensional deployments
+  **Merge generator** - Merge parameters from multiple generators

For complete generator reference, see [ApplicationSet Documentation](https://argo-cd.readthedocs.io/en/stable/user-guide/application-set/).

## List generator
<a name="_list_generator"></a>

Deploy to multiple clusters with explicit configuration:

```
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: guestbook-all-clusters
  namespace: argocd
spec:
  generators:
  - list:
      elements:
      - environment: dev
        replicas: "2"
      - environment: staging
        replicas: "3"
      - environment: prod
        replicas: "5"
  template:
    metadata:
      name: 'guestbook-{{environment}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/example/guestbook
        targetRevision: HEAD
        path: 'overlays/{{environment}}'
      destination:
        name: '{{environment}}-cluster'
        namespace: guestbook
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
```

**Note**  
Use `destination.name` with cluster names for better readability. The `destination.server` field also works with EKS cluster ARNs if needed.

This creates three Applications: `guestbook-dev`, `guestbook-staging`, and `guestbook-prod`.

## Cluster generator
<a name="_cluster_generator"></a>

Deploy to all registered clusters automatically:

```
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-addons
  namespace: argocd
spec:
  generators:
  - clusters: {}
  template:
    metadata:
      name: '{{name}}-addons'
    spec:
      project: default
      source:
        repoURL: https://github.com/example/cluster-addons
        targetRevision: HEAD
        path: addons
      destination:
        server: '{{server}}'
        namespace: kube-system
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
```

This automatically creates an Application for each registered cluster.

 **Filter clusters**:

Use `matchLabels` to include specific clusters, or `matchExpressions` to exclude clusters:

```
spec:
  generators:
  - clusters:
      selector:
        matchLabels:
          environment: production
        matchExpressions:
        - key: skip-appset
          operator: DoesNotExist
```

## Git generators
<a name="_git_generators"></a>

Git generators create Applications based on repository structure:
+  **Directory generator** - Deploy each directory as a separate Application (useful for microservices)
+  **File generator** - Generate Applications from parameter files (useful for multi-tenant deployments)

 **Example: Microservices deployment** 

```
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: microservices
  namespace: argocd
spec:
  generators:
  - git:
      repoURL: https://github.com/example/microservices
      revision: HEAD
      directories:
      - path: services/*
  template:
    metadata:
      name: '{{path.basename}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/example/microservices
        targetRevision: HEAD
        path: '{{path}}'
      destination:
        name: my-cluster
        namespace: '{{path.basename}}'
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
        - CreateNamespace=true
```

For details on Git generators and file-based configuration, see [Git Generator](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Generators-Git/) in the Argo CD documentation.

## Matrix generator
<a name="_matrix_generator"></a>

Combine multiple generators to deploy across multiple dimensions (environments × clusters):

```
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: multi-env-multi-cluster
  namespace: argocd
spec:
  generators:
  - matrix:
      generators:
      - list:
          elements:
          - environment: dev
          - environment: staging
          - environment: prod
      - clusters:
          selector:
            matchLabels:
              region: us-west-2
  template:
    metadata:
      name: 'app-{{environment}}-{{name}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/example/app
        targetRevision: HEAD
        path: 'overlays/{{environment}}'
      destination:
        name: '{{name}}'
        namespace: 'app-{{environment}}'
```

For details on combining generators, see [Matrix Generator](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Generators-Matrix/) in the Argo CD documentation.

## Multi-region deployment
<a name="_multi_region_deployment"></a>

Deploy to clusters across multiple regions:

```
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: global-app
  namespace: argocd
spec:
  generators:
  - list:
      elements:
      - clusterName: prod-us-west
        region: us-west-2
      - clusterName: prod-us-east
        region: us-east-1
      - clusterName: prod-eu-west
        region: eu-west-1
  template:
    metadata:
      name: 'app-{{region}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/example/app
        targetRevision: HEAD
        path: kubernetes
        helm:
          parameters:
          - name: region
            value: '{{region}}'
      destination:
        name: '{{clusterName}}'
        namespace: app
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
```

## Manage ApplicationSets
<a name="_manage_applicationsets"></a>

 **View ApplicationSets and generated Applications**:

```
kubectl get applicationsets -n argocd
kubectl get applications -n argocd -l argocd.argoproj.io/application-set-name=<applicationset-name>
```

 **Update an ApplicationSet**:

Modify the ApplicationSet spec and reapply. Argo CD automatically updates all generated Applications:

```
kubectl apply -f applicationset.yaml
```

 **Delete an ApplicationSet**:

```
kubectl delete applicationset <name> -n argocd
```

**Warning**  
Deleting an ApplicationSet deletes all generated Applications. If those Applications have `prune: true`, their resources will also be deleted from target clusters.  
To preserve deployed resources when deleting an ApplicationSet, set `.syncPolicy.preserveResourcesOnDeletion` to `true` in the ApplicationSet spec. For more information, see [Application Pruning & Resource Deletion](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Application-Deletion/) in the Argo CD documentation.

**Important**  
Argo CD’s ApplicationSets feature has security considerations you should be aware of before using ApplicationSets. For more information, see [ApplicationSet Security](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Security/) in the Argo CD documentation.

## Additional resources
<a name="_additional_resources"></a>
+  [Working with Argo CD Projects](argocd-projects.md) - Organize ApplicationSets with Projects
+  [Create Applications](argocd-create-application.md) - Understand Application configuration
+  [ApplicationSet Documentation](https://argo-cd.readthedocs.io/en/stable/user-guide/application-set/) - Complete generator reference and patterns
+  [Generator Reference](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Generators/) - Detailed generator specifications