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

• An EKS cluster with the Argo CD capability created

• Repository access configured (see Configure repository access)

• Target cluster registered (see Register target clusters)

• kubectl configured to communicate with your cluster

Create a basic Application

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

Create an Application in an additional namespace

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.

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

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

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:

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

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 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 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 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 for details.

Kustomize:

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

Push hydrated manifests with the source hydrator

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.

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

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

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.

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:

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.

Sync policies

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

Additional sync configuration:

Create namespace if it does not exist:

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

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

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 and Resource Hooks in the Argo CD documentation.

Ignore differences

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 in the Argo CD documentation.

Multi-environment deployment

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

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 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 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 in the Argo CD documentation.

Additional resources

• Working with Argo CD Projects - Organize applications with Projects for multi-tenant environments

• Use ApplicationSets - Deploy to multiple clusters with templates

• Application Specification - Complete Application API reference

• Sync Options - Advanced sync configuration