Skip to main content
Understanding the Argo CD Application resource is essential for implementing GitOps workflows with Argo CD. An Application is a Kubernetes custom resource (CR) that describes a deployed software instance — the desired state (manifests, charts, kustomize overlays, etc.) and where to apply it. Argo CD then continuously reconciles the live cluster to match this desired state. Key concepts:
  • GitOps: store desired state in Git and let Argo CD sync it to clusters.
  • Application: the CR that binds a source (Git/Helm/Plugins) to a destination (cluster + namespace).
  • Sync Policy: controls automated sync, pruning, and self-healing behavior.

​
How to create an Argo CD Application

You can create an Application using:
  • argocd CLI
  • a Kubernetes YAML manifest applied with kubectl
  • the Argo CD web UI
Example: create an application from a Git repository using the CLI 
argocd app create color-app \
  --repo https://github.com/sid/app-1.git \
  --path team-a/color-app \
  --dest-namespace color \
  --dest-server https://kubernetes.default.svc
After creation, Argo CD can automatically synchronize manifests from the Git repository to the configured destination cluster and namespace.

​
Example Application manifest

This YAML corresponds to the CLI example above. It shows common fields and an automated sync policy. 
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: color-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: 'https://github.com/sid/app-1.git'
    targetRevision: HEAD
    path: team-a/color-app
  destination:
    server: 'https://kubernetes.default.svc'
    namespace: color
  syncPolicy:
    automated:
      prune: false
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

​
Manifest fields (reference)

FieldPurposeNotes / Example
metadata.nameName of the Application resourcee.g., color-app
metadata.namespaceNamespace where Argo CD is installedcommonly argocd
spec.projectThe Argo CD Project that owns the ApplicationProjects can enforce allowed repos/destinations
spec.source.repoURLGit repository containing manifestse.g., https://github.com/sid/app-1.git
spec.source.targetRevisionGit branch/tag/commit to usee.g., HEAD, main, v1.0.0
spec.source.pathPath in repo to manifests or charte.g., team-a/color-app
spec.destination.serverKubernetes API server to deploy tohttps://kubernetes.default.svc for in-cluster
spec.destination.namespaceTarget namespace in destination clustere.g., color
spec.syncPolicy.automated.selfHealAuto-rollback manual changes in clustertrue to enforce Git state
spec.syncPolicy.automated.pruneRemove resources not in Git during synctrue to enable pruning
spec.syncPolicy.syncOptionsExtra sync optionse.g., CreateNamespace=true

​
Source vs Destination

  • Source: where Argo CD reads the desired state from — can be plain YAML, Helm charts, Kustomize overlays, Jsonnet, or custom plugins. The Application’s source block points Argo CD to the correct repo/path/revision and triggers rendering as needed.
  • Destination: the Kubernetes cluster and namespace where resources are applied. The destination.server can reference the in-cluster API (https://kubernetes.default.svc) or an external cluster registered in Argo CD.

​
Sync policies and options

  • Automated sync: instructs Argo CD to apply changes in Git automatically.
  • Self-heal: when enabled, Argo CD will revert out-of-band (manual) changes on cluster resources to match Git.
  • Prune: if enabled, resources that no longer exist in the Git source will be deleted from the cluster on sync.
  • CreateNamespace: a syncOption that tells Argo CD to create the target namespace if missing (requires proper RBAC).
When using automated sync and CreateNamespace, ensure Argo CD’s ServiceAccount has sufficient RBAC permissions to create namespaces and manage the required resource types in the destination cluster. For multi-cluster setups, confirm projects restrict allowed destinations to avoid accidental deployments.

​
Best practices and cautions

  • Use Argo CD Projects to limit the repositories and clusters an Application can target.
  • Test automated sync and pruning in non-production environments before enabling in production.
  • Use branch/tag commit pins (targetRevision) for predictable deployments.
  • Ensure secrets and credentials (to clusters, registries) are stored securely and referenced via Argo CD mechanisms (Secrets, SSO integrations, or external secret stores).
Be cautious with automated sync and pruning in production clusters. Misconfigured paths, overly permissive projects, or insufficient RBAC checks can lead to unintended deletions or rollbacks.
This overview should help you create and manage Argo CD Application resources safely, with clear expectations for sync behavior and RBAC requirements.

Watch Video