How to Define Applications in Argo CD: The Complete Guide to Application CRDs

You define Argo CD applications by creating an Application custom resource (CRD) that declaratively links a source repository containing Kubernetes manifests to a target cluster destination, along with sync policies and project membership.

Argo CD manages Kubernetes workloads through the declarative Application custom resource. As implemented in the argoproj/argo-cd repository, this resource type connects your Git repository to a target cluster, enabling GitOps-driven continuous delivery for Helm charts, Kustomize overlays, or plain YAML manifests.

Core Concepts of the Application Resource

The Application resource ties together three fundamental concepts that Argo CD reconciles continuously. According to the source code in pkg/apis/application/v1alpha1/types.go (lines 76-88), the ApplicationSpec struct orchestrates these relationships:

• Source – The Git repository, Helm chart repository, or plugin location containing your manifests
• Destination – The target Kubernetes cluster API endpoint and namespace where resources are deployed
• Project & Sync Policy – Logical grouping via AppProject, access controls, and automated synchronization behaviors

Anatomy of the ApplicationSpec

The ApplicationSpec defined in pkg/apis/application/v1alpha1/types.go contains the core fields that determine how Argo CD manages your deployment.

Source Configuration

The source field (or sources for multi-source applications) is defined by the ApplicationSource struct (lines 95-124). It supports multiple manifest generation methods:

• Git repositories: Specify repoURL, path, and targetRevision
• Helm charts: Use the helm sub-field with values, valueFiles, and helm.version
• Kustomize: Configure kustomize sub-fields for namePrefix, nameSuffix, and patches
• Directory: Enable directory.recurse for recursive manifest application
• Config Management Plugins: Reference external tools via the plugin field

Destination Configuration

The destination field maps to ApplicationDestination (lines 127-132). It requires:

• server: The cluster API URL (or https://kubernetes.default.svc for the in-cluster deployment)
• namespace: The target namespace where resources are created

Project Assignment

The project field (lines 82-84) assigns the application to an AppProject. An empty value defaults to the default project, which controls repository access and destination whitelisting.

Sync Policy and Automation

The syncPolicy field (lines 134-157) controls deployment automation through:

• Automated sync: spec.syncPolicy.automated with prune, selfHeal, and allowEmpty boolean flags
• Sync options: spec.syncPolicy.syncOptions array including CreateNamespace=true, PruneLast=true, and RespectIgnoreDifferences=true
• Retry logic: spec.syncPolicy.retry for configuring backoff strategies on failed syncs

Advanced Configuration Options

• ignoreDifferences: Lists resource fields to exclude from drift detection (lines 87-95). Useful for ignoring replica counts managed by Horizontal Pod Autoscalers.
• info: Arbitrary key-value pairs displayed in the Argo CD UI for documentation or external links.
• sourceHydrator: Enables "dry-run → hydrate → commit" workflows (lines 101-103) for generating manifests before synchronization.

Practical Application Examples

Basic Git-Based Application

The most common pattern references a Git repository with plain YAML manifests:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: nginx-demo
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/nginx-manifests.git
    targetRevision: main
    path: overlays/production
  destination:
    server: https://kubernetes.default.svc
    namespace: nginx
  syncPolicy:
    automated:
      enable: true
      prune: true
      selfHeal: true

Helm Application with Custom Values

For Helm charts, specify the chart name and override values:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: prometheus
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://charts.helm.sh/stable
    chart: prometheus
    targetRevision: 14.0.0
    helm:
      values: |
        server:
          replicaCount: 2
      valueFiles:
        - values-prod.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: monitoring
  syncPolicy:
    automated:
      enable: true
      prune: true

Kustomize with Transformations

Reference Kustomize overlays directly with built-in transformations:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: multi-env
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/multi-env.git
    targetRevision: develop
    path: base
    kustomize:
      namePrefix: dev-
      commonLabels:
        env: dev
  destination:
    server: https://kubernetes.default.svc
    namespace: dev
  syncPolicy:
    automated:
      enable: true

Handling Configuration Drift

Use ignoreDifferences to prevent Argo CD from reverting changes made by autoscalers or external controllers:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: scaled-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/scaled-app.git
    path: .
    targetRevision: HEAD
  destination:
    server: https://kubernetes.default.svc
    namespace: prod
  ignoreDifferences:
  - group: apps
    kind: Deployment
    jsonPointers:
    - /spec/replicas
  syncPolicy:
    automated:
      enable: true
      selfHeal: true

How the Controller Reconciles Applications

The Argo CD server watches Application objects via the Kubernetes API and reconciles them continuously. As implemented in server/application/application.go, the controller performs these steps:

1. Source retrieval – Clones the Git repository or fetches the Helm chart at the specified targetRevision
2. Manifest generation – Processes templates based on the source type (Helm, Kustomize, or plain YAML) defined in ApplicationSource
3. Drift detection – Compares the generated manifests against live cluster resources, respecting ignoreDifferences configurations
4. Synchronization – Applies changes to the destination cluster when manual sync is triggered or when spec.syncPolicy.automated is enabled
5. Status updates – Writes back sync status, health status, and operation results to the Application resource status subresource

For a comprehensive reference covering every optional field, see the canonical example in docs/operator-manual/application.yaml in the argoproj/argo-cd repository.

Summary

• Application CRD: The Application resource in apiVersion: argoproj.io/v1alpha1 is the fundamental unit of deployment in Argo CD, defined in pkg/apis/application/v1alpha1/types.go
• Required fields: Every application requires a source (where manifests live), destination (target cluster and namespace), and project (access control scope)
• Multi-source support: Use the sources array (plural) instead of source when combining multiple repositories or charts
• Automation: Enable syncPolicy.automated for self-healing infrastructure that automatically corrects drift and prunes orphaned resources
• Hydration workflows: Advanced users can enable sourceHydrator for pre-processing manifests before deployment

Frequently Asked Questions

What is the difference between source and sources in an Application?

The source field accepts a single ApplicationSource object for simple deployments from one repository. The sources field accepts an array of sources, allowing you to combine a Helm chart from one repository with values or patches from another. Both are defined in pkg/apis/application/v1alpha1/types.go lines 95-124.

How do I target a specific cluster instead of the in-cluster destination?

In the destination.server field, specify the cluster URL (e.g., https://my-cluster.example.com:6443) rather than https://kubernetes.default.svc. You can also use destination.name to reference a cluster by the name registered in Argo CD's secrets, as validated in server/application/application.go.

Where can I find the complete schema for all Application fields?

The canonical reference is docs/operator-manual/application.yaml in the argoproj/argo-cd repository, which contains commented examples of every optional field including syncPolicy.syncOptions, ignoreDifferences, and sourceHydrator configurations.

What happens if I don't specify a project in the Application spec?

If the project field is omitted or set to an empty string, Argo CD automatically assigns the application to the default project. This behavior is hardcoded in the ApplicationSpec struct definition at lines 82-84 of pkg/apis/application/v1alpha1/types.go. The default project restricts source repositories and destination clusters based on global Argo CD configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}