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

> Learn to define Argo CD applications using Application CRDs. Connect repositories to clusters declaratively with sync policies and project membership. Your complete guide to Argo CD app definitions.

- Repository: [Argo Project/argo-cd](https://github.com/argoproj/argo-cd)
- Tags: how-to-guide
- Published: 2026-07-14

---

**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`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/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:

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/server/application/application.go).

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

The canonical reference is [`docs/operator-manual/application.yaml`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/pkg/apis/application/v1alpha1/types.go). The default project restricts source repositories and destination clusters based on global Argo CD configuration.