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

> Learn to define Argo CD applications using the Application CRD. This guide covers specifying repositories, destinations, and sync policies for effective cluster management.

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

---

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

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

```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 Configuration

Apply Kustomize transformations during synchronization:

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

```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
    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`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/docs/operator-manual/application.yaml)** – Provides a comprehensive example covering every optional field including Helm, Kustomize, and plugin configurations.
- **[`server/application/application.go`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/docs/user-guide/application-specification.md)** – User-facing documentation referencing the YAML schema and field descriptions.
- **[`docs/user-guide/sync-options.md`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/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.