Argo CD Application Manifest: Anatomy of the Application CRD

The Argo CD application manifest is a Kubernetes CustomResourceDefinition (CRD) that declaratively defines how to deploy and manage applications from Git repositories, Helm charts, or Kustomize directories to target clusters.

The Argo CD application manifest is the foundational configuration object that enables GitOps workflows in the argoproj/argo-cd repository. As a native Kubernetes resource in the argoproj.io/v1alpha1 API group, it bridges source code repositories with live cluster state through declarative configuration defined in YAML.

What Is the Argo CD Application Manifest?

An Argo CD application manifest is a YAML document that creates an Application object (kind: Application) in your Kubernetes cluster. This CRD, defined in manifests/crds/application-crd.yaml, serves as the contract between your desired state (stored in Git) and your actual cluster state. The manifest declares where to find application definitions, where to deploy them, and how to handle synchronization.

The schema is versioned and validated through the OpenAPI specification in manifests/crds/application-crd.yaml, while the Go structs mapping to this CRD reside in pkg/apis/application/v1alpha1/types.go. When applied, the Argo CD application controller watches these objects and performs reconciliation via the logic in server/application/application.go.

Core Manifest Sections

Source Configuration (spec.source)

The spec.source field defines where Argo CD retrieves your Kubernetes manifests. It supports multiple tooling options including plain Git directories, Helm charts, Kustomize overlays, Jsonnet, and custom plugins.

Key sub-fields include:

• repoURL: The Git repository or Helm chart repository URL
• targetRevision: Branch, tag, or commit SHA to checkout
• path: Directory path within the repository (for Git sources)
• helm: Helm-specific configuration including values, parameters, and valueFiles
• kustomize: Kustomize settings for namePrefix, images, and patches

Since version 2.2, Argo CD supports multiple sources via spec.sources, enabling composition patterns where you combine a base chart with environment-specific overlays.

Destination Configuration (spec.destination)

The spec.destination section specifies the target cluster and namespace:

• server: API server URL of the target cluster (use https://kubernetes.default.svc for the local cluster)
• namespace: Target namespace where resources will be created

Combined with spec.project (which assigns the Application to a logical Argo CD Project), this determines access controls and deployment boundaries.

Sync Policy and Automation (spec.syncPolicy)

The spec.syncPolicy field controls how Argo CD applies changes to your cluster:

• automated: Enables automatic syncing when drift is detected, with options for prune (remove unexpected resources) and selfHeal (correct manual changes)
• syncOptions: Fine-grained controls like CreateNamespace=true or PrunePropagationPolicy=foreground
• retry: Back-off strategies for failed sync attempts

Diff Management (spec.ignoreDifferences)

The spec.ignoreDifferences field tells the controller which fields to ignore when comparing live state against desired state. You can specify JSON pointers, jq expressions, or managed-fields managers to exclude expected drift from sync calculations.

Additional fields include:

• revisionHistoryLimit: Number of historic revisions to retain for rollbacks
• sourceHydrator: Optional hydration step for generating manifests from dry sources
• info: Arbitrary key-value pairs displayed in the UI for documentation or ticketing links

Practical Examples

Basic Git Repository Application

This minimal example deploys from a plain Git directory to the default cluster:

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

Reference: See the full annotated example in docs/operator-manual/application.yaml.

Helm-Based Deployment

Configure Helm-specific parameters under spec.source.helm:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: helm-demo
spec:
  project: default
  source:
    repoURL: https://charts.helm.sh/stable
    chart: nginx
    targetRevision: 1.2.3
    helm:
      values: |
        service:
          type: LoadBalancer
      parameters:
        - name: replicaCount
          value: "3"
  destination:
    server: https://kubernetes.default.svc
    namespace: nginx
  syncPolicy:
    automated:
      prune: true

Reference: Helm field definitions are located in manifests/crds/application-crd.yaml under spec.source.helm.

Kustomize Configuration

Override images and apply patches using Kustomize options:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: kustomize-demo
spec:
  source:
    repoURL: https://github.com/example/repo.git
    path: overlays/prod
    kustomize:
      namePrefix: prod-
      images:
        - nginx=nginx:1.19-alpine
      patches:
        - target:
            kind: Deployment
            name: web
          patch: |
            - op: replace
              path: /spec/replicas
              value: 4
  destination:
    server: https://kubernetes.default.svc
    namespace: prod
  syncPolicy:
    automated:
      selfHeal: true

Controller Reconciliation

The Argo CD application controller continuously watches Application objects defined in your manifests. According to the implementation in server/application/application.go, the controller:

1. Resolves the source location (Git/Helm/Kustomize)
2. Renders manifests using the specified tooling
3. Applies resources to the destination cluster
4. Tracks health status and sync state
5. Updates the Application object's status subresource with conditions and operation history

The controller uses the Go types defined in pkg/apis/application/v1alpha1/types.go to marshal and unmarshal these manifests during reconciliation.

Summary

• The Argo CD application manifest is a Kubernetes CRD (argoproj.io/v1alpha1) that declaratively configures GitOps deployments
• Schema definition resides in manifests/crds/application-crd.yaml with reference examples in docs/operator-manual/application.yaml
• Core sections include spec.source (Git/Helm/Kustomize), spec.destination (cluster/namespace), and spec.syncPolicy (automation rules)
• Multi-source support (v2.2+) enables complex composition patterns via spec.sources
• Controller logic in server/application/application.go handles reconciliation, health checking, and drift detection

Frequently Asked Questions

What is the difference between an Application and an AppProject in Argo CD?

An Application defines a specific deployment (what to deploy and where), while an AppProject (kind: AppProject) is a logical grouping that defines access controls, resource allowlists, and role-based access for multiple Applications. Projects live in spec.project fields within Application manifests.

How do I reference a private Git repository in an Argo CD application manifest?

Private repositories require configuring a Repository Credential or SSH key in Argo CD settings before referencing them in spec.source.repoURL. The manifest itself remains unchanged—you simply specify the private URL in repoURL, and Argo CD uses the stored credentials to authenticate.

Can I deploy multiple Kubernetes resources from different sources using one Application manifest?

Yes. Since Argo CD v2.2, you can use the spec.sources array (plural) instead of spec.source to reference multiple Git repositories, Helm charts, or Kustomize directories. The controller merges these sources during the sync operation, enabling patterns like separating base charts from environment-specific configuration.

Where is the Application CRD schema defined in the Argo CD source code?

The complete OpenAPI schema is defined in manifests/crds/application-crd.yaml. This file contains all field definitions, validation markers, and version specifications for the Application resource. The corresponding Go structs used by the controller are located in pkg/apis/application/v1alpha1/types.go.

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