How to Define Argo CD Applications: Complete Guide to the Application CRD

Argo CD applications are defined as Kubernetes custom resources (CRDs) of kind Application that declaratively specify source repositories, target destinations, and synchronization policies to manage cluster state.

The argoproj/argo-cd project manages Kubernetes workloads through the Application custom resource, which serves as the fundamental unit of deployment. To define Argo CD applications effectively, you must understand the ApplicationSpec structure that connects Git repositories, Helm charts, or Kustomize configurations with specific target clusters.

Core Concepts of Argo CD Applications

An Application resource ties together three essential components:

1. Source – The location of manifest files, Helm charts, or configuration repositories.
2. Destination – The target Kubernetes cluster and namespace where resources are applied.
3. Project and Sync Policy – Logical grouping, access control, and automation settings for synchronization.

The Argo CD controller watches these resources and reconciles the desired state defined in spec.source with the live state in the destination cluster.

The ApplicationSpec Structure

The Application spec is defined in the Go type ApplicationSpec located in pkg/apis/application/v1alpha1/types.go (lines 76‑88). This structure contains fields for single or multiple sources, destination targeting, project membership, and advanced synchronization behaviors.

Source Configuration

The source field (or sources for multiple sources) uses the ApplicationSource type defined at lines 95‑124 in pkg/apis/application/v1alpha1/types.go. This configuration supports:

• Git repositories via repoURL, path, and targetRevision
• Helm charts via the helm sub-field with values and valueFiles
• Kustomize configurations via the kustomize sub-field
• Directory walks for raw YAML
• Config Management Plugins via the plugin field

Destination Targeting

The destination field uses the ApplicationDestination type (lines 127‑132) to specify:

• server: The target cluster API URL (use https://kubernetes.default.svc for in-cluster)
• namespace: The target namespace for resource creation

Sync Policies and Automation

The syncPolicy field (referencing SyncPolicy at lines 134‑157) controls:

• Automated sync: Enable with automated.enable: true
• Pruning: Remove resources no longer in Git with automated.prune: true
• Self-healing: Revert manual changes with automated.selfHeal: true
• Sync options: Include CreateNamespace=true in syncPolicy.syncOptions to auto-create namespaces

Advanced Configuration Options

• ignoreDifferences: Configure at spec.ignoreDifferences to exclude specific fields (like replica counts) from drift detection. This uses the IgnoreDifferences type defined in the source.
• sourceHydrator: Enable at spec.sourceHydrator for "dry-run → hydrate → commit" workflows where manifests are generated and committed back to Git before synchronization.
• info: Add arbitrary key-value pairs displayed in the Argo CD UI for documentation or external links.

Practical YAML Examples

Basic Git Repository Application

The most common pattern defines an application from a plain Git repository containing Kubernetes manifests:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argo-cd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook
  syncPolicy:
    automated:
      enable: true
      prune: true
      selfHeal: true

Helm Chart Deployment

Deploy Helm charts from chart repositories with custom 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 Configuration

Apply Kustomize transformations during synchronization:

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 manual scaling operations:

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

Key Source Files and References

Understanding how to define Argo CD applications requires familiarity with these specific files in the argoproj/argo-cd repository:

• pkg/apis/application/v1alpha1/types.go – Contains the canonical Go definitions for ApplicationSpec, ApplicationSource, ApplicationDestination, and SyncPolicy (lines 76‑157).
• docs/operator-manual/application.yaml – Provides a comprehensive example covering every optional field including Helm, Kustomize, and plugin configurations.
• server/application/application.go – Implements the server-side controller logic that validates and reconciles Application objects against cluster state.
• docs/user-guide/application-specification.md – User-facing documentation referencing the YAML schema and field descriptions.
• docs/user-guide/sync-options.md – Details available synchronization options for spec.syncPolicy.syncOptions.

Summary

To define Argo CD applications effectively:

• Define an Application CRD with apiVersion: argoproj.io/v1alpha1 and kind: Application.
• Configure the source field to point to Git repositories, Helm charts, or Kustomize configurations using the ApplicationSource structure.
• Set the destination with the target cluster API server URL and namespace using ApplicationDestination.
• Use syncPolicy.automated to enable self-healing, pruning, and automatic synchronization.
• Reference pkg/apis/application/v1alpha1/types.go for the exact field definitions and constraints implemented by the controller.

Frequently Asked Questions

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

The source field defines a single source location for manifests, while sources accepts a list of ApplicationSource objects for multi-source applications. Use sources when you need to combine manifests from multiple Git repositories, Helm charts, or mix different configuration types (such as Helm and Kustomize) into a single deployment.

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

Specify the external cluster's API server URL in destination.server (e.g., https://cluster-api.example.com:6443) and ensure the cluster is registered in Argo CD under Settings > Clusters. You must also verify that the project assigned to the application has permissions to deploy to that destination cluster and namespace, as defined in the AppProject resource.

What happens if I omit the project field 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 project typically allows deployments from any source repository to any destination cluster, though administrators can restrict this behavior. Always explicitly set project to enforce proper RBAC and resource isolation in production environments.

How do I enable automatic namespace creation during synchronization?

Add CreateNamespace=true to the syncPolicy.syncOptions array in your Application spec. When this option is enabled, Argo CD automatically creates the namespace specified in destination.namespace if it does not already exist, eliminating the need for manual namespace creation or separate namespace manifests in your Git repository.

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