ArgoCD Application Specifications

In this lesson we’ll cover the structure and key fields of an Argo CD Application resource — the core Kubernetes Custom Resource that describes a deployable software instance under GitOps control. An Argo CD Application ties together:

the source of truth for your desired state (Git repository, path, branch/tag, or chart),
and the destination where those manifests should be applied (Kubernetes API server and namespace).

This document explains how to create an Application (CLI and manifest), what Argo CD does after creation, and a concise reference for the most important fields.

Create an Application (CLI)

A common way to create an application is with the argocd CLI. The example below creates an application that points to a Git repository and a path inside that repo:

argocd app create color-app \
  --repo https://github.com/sid/app-1.git \
  --path team-a/color \
  --dest-namespace color \
  --dest-server https://kubernetes.default.svc
# Application 'color-app' created

After you create the Application, Argo CD continuously compares the live cluster state against the Git-specified desired state and will deploy or reconcile resources according to the configured sync policy.

An Argo CD Application has two primary parts:

source: where the desired manifests live (Git repo, path, branch/tag, Helm chart, Kustomize or Jsonnet).
destination: the target Kubernetes API server and namespace where resources should be applied.

Example Application manifest

Below is a representative Application manifest for the same app created above:

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
  destination:
    server: 'https://kubernetes.default.svc'
    namespace: color
  syncPolicy:
    automated:
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Key fields explained

Field	Purpose	Example / Notes
`metadata.name` / `metadata.namespace`	Identifies the Application resource and the namespace where Argo CD control plane runs	`name: color-app` `namespace: argocd`
`spec.project`	Associates the Application with an Argo CD Project to enforce repo/cluster/namespace policies	`project: default`
`spec.source`	Where to retrieve and how to render the desired state (Git repo, path, branch/tag, Helm chart, Kustomize, Jsonnet)	`repoURL: 'https://github.com/sid/app-1.git'` `targetRevision: HEAD` `path: team-a/color`
`spec.destination`	The target Kubernetes API server and namespace where resources will be applied	`server: 'https://kubernetes.default.svc'` (in-cluster) `namespace: color`
`spec.syncPolicy`	How Argo CD should keep cluster state in sync with Git (automated/manual, self-heal, sync options)	Example: `automated: { selfHeal: true }` Sync option: `CreateNamespace=true`

Notes on `spec.source`

Supports multiple formats: Git manifests, Helm charts, Kustomize overlays, and Jsonnet.
targetRevision accepts a branch name, tag, or commit SHA (default: HEAD).

Notes on `spec.destination`

For in-cluster deployments use https://kubernetes.default.svc.
For external clusters use the API server URL as registered in Argo CD (via argocd cluster add or the UI).

Notes on `spec.syncPolicy`

automated causes Argo CD to automatically apply Git changes.
selfHeal: true instructs Argo CD to detect and revert out-of-band changes made directly in the cluster.
Use syncOptions (for example, CreateNamespace=true) to control sync-time behaviors.

Common use cases and behavior

Continuous delivery: Argo CD watches the Git repo and automatically synchronizes changes (when automated is enabled).
Drift detection & remediation: With selfHeal: true, Argo CD restores cluster state when manual changes diverge from Git.
Multi-cluster deployments: Use destination.server values that target different clusters registered in Argo CD.

References and further reading

Argo CD official docs: https://argo-cd.readthedocs.io/
GitOps overview: https://www.gitops.tech/
Helm: https://helm.sh/
Kustomize: https://kubectl.docs.kubernetes.io/references/kustomize/
Jsonnet: https://jsonnet.org

For step-by-step tutorials and deeper examples, see the Argo CD documentation and community guides linked above.

Introduction

GitOps Terminology

GitOps Principles

GitOps Patterns

Tooling

Related Practices

ArgoCD Application Specifications

Create an Application (CLI)

Example Application manifest

Key fields explained

Notes on `spec.source`

Notes on `spec.destination`

Notes on `spec.syncPolicy`

Common use cases and behavior

References and further reading

Watch Video

​Create an Application (CLI)

​Example Application manifest

​Key fields explained

​Notes on spec.source

​Notes on spec.destination

​Notes on spec.syncPolicy

​Common use cases and behavior

​References and further reading

Watch Video

Create an Application (CLI)

Example Application manifest

Key fields explained

Notes on `spec.source`

Notes on `spec.destination`

Notes on `spec.syncPolicy`

Common use cases and behavior

References and further reading