Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 37 ยท Applications and Projects

The Argo CD Application Manifest: Every Field Explained

Read and write the Argo CD Application custom resource: metadata and finalizers, project, source, destination, syncPolicy, ignoreDifferences, info and revisionHistoryLimit, with a linter you can run.

The Application custom resource is the heart of Argo CD. Everything else (projects, sync, hooks, ApplicationSets) exists to create, constrain or operate Applications. In this lesson you will read the whole manifest top to bottom, so no field looks mysterious later.

The YAML is real Argo CD syntax (API group argoproj.io/v1alpha1). It cannot be applied from this site, so the runnable blocks are stand-ins: a linter that checks an Application written as a JavaScript object, and a builder that prints YAML. Verify details against the version of Argo CD you run.

The full shape

YAML
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: shop-production
  namespace: argocd
  labels:
    team: storefront
    env: production
  annotations:
    notifications.argoproj.io/subscribe.on-sync-failed.slack: storefront-alerts
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: storefront
  source:
    repoURL: https://github.com/example/config.git
    targetRevision: main
    path: apps/shop/overlays/production
  destination:
    server: https://kubernetes.default.svc
    namespace: shop
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/replicas
  info:
    - name: Runbook
      value: https://wiki.example.com/shop
  revisionHistoryLimit: 10

metadata

  • name is unique within the Argo CD namespace. Names like shop-production (app plus environment) scale better than shop.
  • namespace is normally argocd, though Argo CD can be configured to watch Applications in other namespaces ("apps in any namespace").
  • labels are for filtering (argocd app list -l team=storefront, UI filters) and for ApplicationSet selection.
  • annotations drive notifications and a few controls, such as argocd.argoproj.io/refresh: normal.
  • finalizers control cleanup. With resources-finalizer.argocd.argoproj.io, deleting the Application also deletes the resources it created (a cascade delete). Without it, the resources stay behind, orphaned. There are also resources-finalizer.argocd.argoproj.io/background (delete in the background) and a foreground variant.

A cascade delete of a production Application removes its Deployments, Services and (depending on the resources) even PersistentVolumeClaims. Protect important apps with a project that denies deletion, careful RBAC, or sync option Delete=false on sensitive resources.

spec.project

Names the AppProject that governs this Application. default allows any repository, any cluster and any namespace. The next lessons show how to restrict it.

spec.source and spec.sources

source is a single source with:

  • repoURL: Git or Helm repository URL (or OCI).
  • targetRevision: a branch, tag, commit SHA or HEAD. For Helm charts it can be a version or a semantic version range such as 1.*.
  • path: the directory in Git (for charts in Git and plain manifests).
  • one tool block: directory, helm, kustomize or plugin.

Since Argo CD 2.6 you can also write sources: (a list) to combine several repositories, for example a Helm chart from one repository with a values file from another. A list and a single source are mutually exclusive.

spec.destination

Either server (the cluster API URL) or name (the cluster's registered name), never both, plus namespace. The in-cluster address is https://kubernetes.default.svc (name in-cluster).

spec.syncPolicy

Controls automation: automated (with prune, selfHeal, allowEmpty), syncOptions, retry and managedNamespaceMetadata. The whole of Sync Policies is devoted to it.

ignoreDifferences, info and history

  • ignoreDifferences excludes fields from the diff (by jsonPointers, jqPathExpressions or managedFieldsManagers).
  • info adds name/value pairs shown in the UI, handy for runbook links.
  • revisionHistoryLimit is how many past syncs are kept for rollback; the default is 10.

Stand-in: an Application linter

This linter checks common mistakes in an Application written as an object. Fix the problems and run it again until it prints "OK".

JS Stand-in: Application linter

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: generate the YAML

Writing many Applications by hand is repetitive. This builder produces consistent YAML from a few inputs, a tiny version of what ApplicationSets do for you.

JS Stand-in: Application YAML builder

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Where do Applications live?

In Git, next to everything else. A directory clusters/production/ can hold one Application file per workload. A single "root" Application then points at that directory, so adding an app is a pull request. That is the app-of-apps pattern, and ApplicationSets automate it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the resources-finalizer.argocd.argoproj.io finalizer do?

    It triggers a cascade delete; without it the deployed resources are left orphaned.
  2. 2. Which pair of fields can NOT be set together in spec.destination?

    Identify the cluster by server URL or by registered name, not both.
  3. 3. What is spec.sources (plural) for?

    Multi-source Applications combine, for example, a chart from one place with values from another. It cannot be mixed with spec.source.
  4. 4. In which namespace do Application objects normally live?

    Applications are stored in Argo CD's namespace; destination.namespace is where workloads go.

Summary

  • An Application = metadata + project + source(s) + destination + sync policy (+ extras).
  • Use the resources finalizer on purpose: it decides what happens on delete.
  • Identify a cluster by server or name; pin targetRevision to a branch, tag or SHA.
  • sources lets you combine repositories; it excludes source.
  • ignoreDifferences, info and revisionHistoryLimit tune diff, UI and rollback.

Next: Sources and Destinations