Applications

Understanding Argo CD Application CRD structure and lifecycle

The Application CRD is the core resource in Argo CD that represents a deployed application. It defines the relationship between a source repository and a Kubernetes cluster, along with sync policies and configuration options.

Application CRD Structure

An Application is a Kubernetes Custom Resource Definition (CRD) that declaratively defines a deployed application instance.

Basic Application Manifest

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
  # Add finalizer for cascading deletion
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  # The project the application belongs to
  project: default
  
  # Source of the application manifests
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  
  # Destination cluster and namespace
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook

Core Components

Source Configuration

The source field defines where your application manifests are stored:

Git Repository

source:
  repoURL: https://github.com/argoproj/argocd-example-apps.git
  targetRevision: HEAD  # branch, tag, or commit SHA
  path: guestbook       # directory path in repo

Destination Configuration

The destination field specifies where the application should be deployed:

destination:
  # Cluster API URL
  server: https://kubernetes.default.svc
  # Or use cluster name
  # name: in-cluster
  
  # Target namespace
  namespace: guestbook

The namespace will only be set for namespace-scoped resources that have not set a value for .metadata.namespace.

Multi-Source Applications

Starting with Argo CD v2.6, applications can have multiple sources:

spec:
  sources:
    - repoURL: https://github.com/org/app-manifests.git
      targetRevision: HEAD
      path: manifests
    - repoURL: https://github.com/org/app-values.git
      targetRevision: main
      path: helm-values
      ref: values-repo
  destination:
    server: https://kubernetes.default.svc
    namespace: my-app

Application Status

The Application status provides real-time information about the deployed state:

Health Status

health.status · string

Current health of the application. Possible values:

• Healthy - All resources are healthy
• Progressing - Application is being deployed or updated
• Degraded - One or more resources are unhealthy
• Suspended - Application is suspended
• Missing - Resources are missing from the cluster
• Unknown - Health status cannot be determined

Sync Status

sync.status · string

Comparison result between live state and desired state:

• Synced - Live state matches desired state
• OutOfSync - Live state differs from desired state
• Unknown - Sync status cannot be determined

Application Lifecycle

Creation

Applications can be created via:

1. Declaratively via kubectl

   kubectl apply -f application.yaml
   
2. Using Argo CD CLI

   argocd app create guestbook \
     --repo https://github.com/argoproj/argocd-example-apps.git \
     --path guestbook \
     --dest-server https://kubernetes.default.svc \
     --dest-namespace guestbook
   
3. Through the Web UI

   Navigate to Applications → New App and fill in the form

Sync Operation

A sync operation deploys the desired state to the target cluster:

# Manual sync
argocd app sync guestbook

# Sync with options
argocd app sync guestbook --prune --force

Deletion

When an Application is deleted, resources are handled based on the finalizer:

metadata:
  finalizers:
    # Foreground cascading deletion (default)
    - resources-finalizer.argocd.argoproj.io
    # Or background cascading deletion
    # - resources-finalizer.argocd.argoproj.io/background

Without a finalizer, deleting the Application CR will NOT delete the deployed resources from the cluster.

Ignore Differences

You can configure Argo CD to ignore certain differences during comparison:

spec:
  ignoreDifferences:
    # Ignore replicas field in Deployments
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/replicas
    
    # Ignore specific ConfigMap data
    - kind: ConfigMap
      jqPathExpressions:
        - '.data["config.yaml"]'
    
    # Ignore fields managed by specific controllers
    - group: "*"
      kind: "*"
      managedFieldsManagers:
        - kube-controller-manager

Revision History

Argo CD maintains a history of sync operations:

spec:
  # Limit the number of stored revisions (default: 10)
  revisionHistoryLimit: 10

View sync history:

argocd app history guestbook

Application Information

Add custom metadata visible in the UI:

spec:
  info:
    - name: 'Documentation'
      value: 'https://docs.example.com'
    - name: 'Contact'
      value: '[e-mail]'

Resource Tracking

Argo CD tracks application resources using labels and annotations. The default tracking method uses the app.kubernetes.io/instance label:

metadata:
  labels:
    app.kubernetes.io/instance: guestbook

Next Steps

Learn about automated sync policies and sync strategies