The Application: Argo CD's unit of deployment

4 min read

Prerequisites: argocd

An Application is the object you write to tell argocd “take what is at this path in this git repository and make it exist in this cluster and namespace, and keep it that way”. It is a custom resource the Argo CD install registers, and it is the single unit the application-controller reconciles. Almost everything you do with Argo CD is writing, reading, or watching Applications. This note pins down its fields and its sync behaviour, because every other GitOps note assumes you know what an Application is.

The three parts

A minimal Application has a source, a destination, and a sync policy. Read this one field by field.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: hello
  namespace: argocd            # Applications live in the argocd namespace
spec:
  project: default             # which AppProject's guardrails apply
  source:
    repoURL: https://github.com/PragalvaXFREZ/lab.git
    targetRevision: main       # branch, tag, or commit to track
    path: kubernetes/apps/hello # the folder in the repo to render
  destination:
    server: https://kubernetes.default.svc   # "this cluster"
    namespace: hello           # where the rendered objects go
  syncPolicy:
    automated:
      selfHeal: true
      prune: true
    syncOptions:
      - CreateNamespace=true
  • source answers “what should exist”. repoURL is the repository, targetRevision is the git ref to follow (track main and it picks up every push; pin a tag or commit and it freezes there), and path is the folder inside the repo whose manifests this Application owns. The argocd repo-server is what renders that path into objects.
  • destination answers “where it goes”. server: https://kubernetes.default.svc is the in-cluster API address and means “the same cluster Argo CD runs in”, which for devata is the only cluster. namespace is where the rendered objects land, unless a manifest names its own namespace.
  • syncPolicy answers “how aggressively to keep it true”, covered below.

Sync state and health are two different questions

For every Application, Argo CD tracks two independent statuses, and confusing them is the most common early mistake.

  • Sync status is Synced or OutOfSync: does the live cluster match what git renders to? OutOfSync means a difference exists, whether or not anything is broken.
  • Health status is Healthy, Progressing, Degraded, and so on: are the objects actually working? Argo CD derives this from the objects themselves, for example a Deployment whose pods are all ready is Healthy.

An app can be Synced and Degraded (git was applied faithfully but the image crashes) or OutOfSync and Healthy (the running version works fine, but git has moved ahead and not been applied yet). You read both, every time.

syncPolicy: manual, automated, self-heal, prune

By default an Application is observe-only. The controller tells you OutOfSync but waits for you to click Sync or run argocd app sync hello. That is manual sync, and it is a reasonable default for things you want a human to release deliberately.

syncPolicy.automated removes the human from the loop and turns the Application into a true reconciliation loop against git. Two flags decide how forceful it is:

  • selfHeal. With auto-sync on, Argo CD applies git whenever the rendered manifests change. selfHeal: true extends that to the other direction: if the live cluster drifts away from git (someone runs kubectl edit), Argo CD pushes it back to git’s version. Without self-heal, drift caused inside the cluster is reported but left alone; with it, git wins every time.
  • prune. When you delete a manifest from git, does Argo CD delete the corresponding live object? With prune: false (the default), removing a file leaves the object orphaned in the cluster and the app OutOfSync, because deleting things is dangerous and Argo CD will not do it without permission. With prune: true, git is fully authoritative: delete the file, and the object is removed. You want pruning on for real GitOps, but it is the flag to think twice about, because a bad git rm becomes a cluster deletion.

syncOptions: [CreateNamespace=true] tells Argo CD to create the destination namespace if it does not exist, so you do not have to pre-create it by hand and break the “everything from git” rule.

Seeing it on a real Application

Once you have Argo CD installed and a hello Application created (the bootstrap walkthrough does this), these are the commands you live in:

argocd app list
argocd app get hello          # source, destination, sync + health, and every managed resource
argocd app diff hello         # exactly what differs between git and the cluster right now
argocd app sync hello         # apply git now (only needed if auto-sync is off)

An Application is therefore a contract: this path in git, applied to this place in the cluster, kept true to this degree. The next note builds one special Application whose job is to create all the others.