

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

# Create Applications

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:

```yaml
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:

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

View the Application status:

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

## Create an Application in an additional namespace
<a name="_create_an_application_in_an_additional_namespace"></a>

You can create Applications outside the primary Argo CD namespace. Before you create the Application, complete the following configuration:
+ Add the namespace to `application.namespaces` in the `argocd-cmd-params-cm` ConfigMap. For instructions on configuring resource namespaces, see [Configure namespaces for Applications and ApplicationSets](argocd-configure-settings.md#argocd-configure-resource-namespaces).
+ Add the namespace to `spec.sourceNamespaces` in the `AppProject` that the Application uses. Create the `AppProject` in the primary Argo CD namespace. For instructions on configuring the AppProject, see [Working with Argo CD Projects](argocd-projects.md).

The following example creates an Application in the `team-a-gitops` namespace that uses the `team-a` project:

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

Apply and view the Application in its source namespace:

```bash
kubectl apply -f application.yaml
kubectl get application guestbook -n team-a-gitops
```

When you use the Argo CD CLI or UI, identify an Application in an additional namespace as `<namespace>/<application-name>`. For example, use `argocd app get team-a-gitops/guestbook`. The namespace that contains the Application is independent of `spec.destination.namespace`, which specifies where Argo CD deploys the workload.

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

 **Git repository**:

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

 **Specific Git tag or commit**:

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

 **Helm chart**:

```yaml
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):

```yaml
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**:

```yaml
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**:

```yaml
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**:

```yaml
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**:

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

## Push hydrated manifests with the source hydrator
<a name="argocd-source-hydrator"></a>

The source hydrator renders your manifests (for example, from Helm charts or Kustomize overlays). It pushes the rendered output to a Git branch before syncing it to the cluster. This implements the rendered manifests pattern: the exact manifests applied to your clusters are stored and auditable in Git.

To turn on the source hydrator, add `hydrator.enabled: "true"` to the `data` section of the `argocd-cmd-params-cm` ConfigMap in the primary Argo CD namespace. Keep any existing keys in the ConfigMap.

```yaml
data:
  hydrator.enabled: "true"
```

To use the source hydrator, Argo CD needs write access to the repository that receives the rendered manifests:
+ For AWS CodeCommit repositories, the Capability Role needs `codecommit:GitPush` in addition to `codecommit:GitPull` (see [Configure Argo CD permissions](argocd-permissions.md)).
+ For all repository types, create a Repository secret labeled `argocd.argoproj.io/secret-type: repository-write`.

In the Application’s `AppProject`, make sure that `spec.sourceRepos` permits the repository used for hydration. For instructions on configuring source repositories in an AppProject, see [Working with Argo CD Projects](argocd-projects.md).

Argo CD uses separate credentials for pushing and pulling to provide better isolation. For Git providers that use stored credentials, such as GitHub or GitLab, create separate pull and write Repository Secrets. The write Secret must contain credentials with write access to the repository.

 **Example – Hydrate a Helm chart from AWS CodeCommit** 

For AWS CodeCommit, the Capability Role provides pull credentials when it has `codecommit:GitPull` permission. You don’t need a pull Repository Secret. Create a write Repository Secret to identify the repository that receives the hydrated output. The Secret doesn’t contain stored credentials because authentication uses the Capability Role. In the following examples, replace `region` with your AWS Region and `repository-name` with your CodeCommit repository name.

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: my-repo-push
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository-write
stringData:
  type: git
  url: https://git-codecommit.{{region}}.amazonaws.com/v1/repos/{{repository-name}}
  project: default
```

**Important**  
The `syncSource.path` field must point to a subdirectory. Hydrating to the repository root is not supported.

Create an Application with `spec.sourceHydrator` instead of `spec.source`:

```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: default
  sourceHydrator:
    drySource:
      repoURL: https://git-codecommit.{{region}}.amazonaws.com/v1/repos/{{repository-name}}
      targetRevision: main
      path: charts/my-app
    syncSource:
      targetBranch: environments/production
      path: my-app-hydrated
  destination:
    name: prod-cluster
    namespace: my-app
```

Argo CD renders the manifests from `drySource`, commits the rendered output to the `environments/production` branch under the `my-app-hydrated` directory, and syncs the cluster from that branch.

(Optional) To stage rendered manifests for review before they sync (for example, through a pull request), add `hydrateTo.targetBranch`. Argo CD then pushes rendered manifests to the staging branch and syncs only from `syncSource.targetBranch`.

For more information about hydrator behavior, commit message templates, and additional options, see [Source Hydrator on the Argo CD documentation website](https://argo-cd.readthedocs.io/en/v3.4.6/user-guide/source-hydrator/).

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

Control how Argo CD syncs applications.

 **Manual sync (default)**:

Applications require manual approval to sync:

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

Manually trigger sync:

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

 **Automatic sync**:

Applications automatically sync when Git changes are detected:

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

 **Self-healing**:

Automatically revert manual changes to the cluster:

```yaml
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:

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

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

 **Combined automated sync**:

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

 **Retry configuration**:

Configure retry behavior for failed syncs:

```yaml
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 does not exist**:

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

 **Skip dry run for missing resources**:

Useful when applying resources that depend on CRDs that do not exist yet (like kro instances):

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

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

 **Validate resources before applying**:

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

 **Apply out of sync only**:

```yaml
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):

```yaml
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**:

```yaml
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**:

```yaml
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**:

```bash
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:

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

**Note**  
For an Application in the primary Argo CD namespace, the namespace prefix is optional. For an Application in an additional namespace, use `<namespace>/<application-name>`.

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