> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/argoproj/argo-cd/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Understand Argo CD's fundamental concepts including Applications, sync status, health checks, and GitOps principles

## Overview

Argo CD operates on GitOps principles, treating Git as the single source of truth for your Kubernetes application state. This page explains the core concepts you need to understand to effectively use Argo CD.

## Application

An **Application** is a group of Kubernetes resources defined by a manifest in a Git repository. It's implemented as a Custom Resource Definition (CRD) in Kubernetes.

### Application Structure

An Application resource defines:

* **Source**: Where to find the application manifests (Git repo, Helm chart, etc.)
* **Destination**: Which cluster and namespace to deploy to
* **Sync Policy**: How and when to synchronize

<CodeGroup>
  ```yaml Basic Application theme={null}
  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: default
  ```

  ```yaml With Helm theme={null}
  apiVersion: argoproj.io/v1alpha1
  kind: Application
  metadata:
    name: myapp
    namespace: argocd
  spec:
    project: default
    source:
      repoURL: https://github.com/example/helm-charts.git
      targetRevision: HEAD
      path: charts/myapp
      helm:
        releaseName: myapp
        valueFiles:
          - values-prod.yaml
        parameters:
          - name: image.tag
            value: v1.2.3
    destination:
      server: https://kubernetes.default.svc
      namespace: production
  ```

  ```yaml With Kustomize theme={null}
  apiVersion: argoproj.io/v1alpha1
  kind: Application
  metadata:
    name: myapp
    namespace: argocd
  spec:
    project: default
    source:
      repoURL: https://github.com/example/kustomize-apps.git
      targetRevision: HEAD
      path: overlays/production
      kustomize:
        namePrefix: prod-
        commonLabels:
          env: production
        images:
          - my-app=gcr.io/my-repo/my-app:v1.2.3
    destination:
      server: https://kubernetes.default.svc
      namespace: production
  ```
</CodeGroup>

## Application Source Type

The **Application Source Type** (also called **Tool**) determines how Argo CD builds your application manifests:

<CardGroup cols={2}>
  <Card title="Plain Kubernetes Manifests" icon="file-code">
    Raw YAML/JSON files in a directory
  </Card>

  <Card title="Helm" icon="box">
    Helm charts from Git repos or Helm registries
  </Card>

  <Card title="Kustomize" icon="layer-group">
    Kustomize overlays and bases
  </Card>

  <Card title="Jsonnet" icon="brackets-curly">
    Jsonnet files with external variables
  </Card>
</CardGroup>

<Note>
  You can also use **Configuration Management Plugins** (CMPs) to support custom tools like Ksonnet, Kapitan, or your own templating solutions.
</Note>

## Target State vs Live State

### Target State

The **target state** is the desired state of your application as represented by files in a Git repository. This is what your application *should* look like according to Git.

```yaml theme={null}
# Git repository defines desired state
apiVersion: apps/v1
kind: Deployment
metadata:
  name: guestbook-ui
spec:
  replicas: 3  # Target: 3 replicas
```

### Live State

The **live state** is the actual state of your application running in the Kubernetes cluster. This is what your application *currently* looks like.

```bash theme={null}
# Actual state in cluster
kubectl get deployment guestbook-ui -o yaml
# Shows: replicas: 1  # Live: 1 replica
```

## Sync Status

**Sync status** indicates whether the live state matches the target state. It answers: "Is the deployed application the same as Git says it should be?"

<CardGroup cols={3}>
  <Card title="Synced" icon="check" color="#2ecc71">
    Live state matches target state
  </Card>

  <Card title="OutOfSync" icon="exclamation-triangle" color="#e74c3c">
    Live state differs from target state
  </Card>

  <Card title="Unknown" icon="question" color="#95a5a6">
    Unable to determine sync status
  </Card>
</CardGroup>

### Viewing Sync Status

```bash theme={null}
# Check sync status via CLI
argocd app get guestbook

# Output includes:
Sync Status:        OutOfSync from (1ff8a67)

GROUP  KIND        NAMESPACE  NAME          STATUS     HEALTH
apps   Deployment  default    guestbook-ui  OutOfSync  Healthy
       Service     default    guestbook-ui  Synced     Healthy
```

## Sync Operation

A **sync** is the process of making an application move to its target state. It applies changes from Git to the Kubernetes cluster.

### Manual Sync

```bash theme={null}
# Sync via CLI
argocd app sync guestbook

# Sync specific resources
argocd app sync guestbook --resource apps:Deployment:guestbook-ui
```

### Automated Sync

Configure automatic synchronization when Git changes are detected:

```yaml theme={null}
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
spec:
  syncPolicy:
    automated:
      enabled: true      # Enable auto-sync
      prune: true        # Delete resources not in Git
      selfHeal: true     # Revert manual changes in cluster
      allowEmpty: false  # Prevent deleting all resources
    syncOptions:
      - CreateNamespace=true
      - PrunePropagationPolicy=foreground
    retry:
      limit: 5           # Retry failed syncs
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m
```

### Sync Operation Status

Indicates whether a sync operation succeeded or failed:

* **Succeeded**: All resources synchronized successfully
* **Failed**: One or more resources failed to sync
* **Running**: Sync is currently in progress

## Refresh

**Refresh** compares the latest code in Git with the live state in the cluster to figure out what's different. It doesn't make changes—it just detects drift.

```bash theme={null}
# Refresh the application state
argocd app get guestbook --refresh

# Hard refresh (bypass cache)
argocd app get guestbook --hard-refresh
```

<Info>
  Argo CD automatically refreshes applications every 3 minutes by default. You can configure this interval in the `argocd-cm` ConfigMap.
</Info>

## Health Status

**Health** indicates the operational state of your application: "Is it running correctly? Can it serve requests?"

<CardGroup cols={2}>
  <Card title="Healthy" icon="heart" color="#2ecc71">
    All resources are healthy and ready
  </Card>

  <Card title="Progressing" icon="spinner" color="#3498db">
    Resources are being created or updated
  </Card>

  <Card title="Degraded" icon="heart-crack" color="#e74c3c">
    One or more resources are unhealthy
  </Card>

  <Card title="Suspended" icon="pause" color="#95a5a6">
    Application is suspended (e.g., CronJob)
  </Card>

  <Card title="Missing" icon="xmark" color="#e74c3c">
    Resources don't exist in the cluster
  </Card>

  <Card title="Unknown" icon="question" color="#95a5a6">
    Health status cannot be determined
  </Card>
</CardGroup>

### Health Assessment

Argo CD determines health based on resource type:

**Deployment**: All replicas are ready

```yaml theme={null}
status:
  availableReplicas: 3
  replicas: 3
  readyReplicas: 3
```

**Service**: Endpoints exist (for non-headless services)

**Pod**: All containers running and ready

**Job**: Job completed successfully

<Accordion title="Custom Health Checks">
  You can define custom health checks for CRDs in the `argocd-cm` ConfigMap:

  ```yaml theme={null}
  apiVersion: v1
  kind: ConfigMap
  metadata:
    name: argocd-cm
    namespace: argocd
  data:
    resource.customizations.health.cert-manager.io_Certificate: |
      hs = {}
      if obj.status ~= nil then
        if obj.status.conditions ~= nil then
          for i, condition in ipairs(obj.status.conditions) do
            if condition.type == "Ready" and condition.status == "False" then
              hs.status = "Degraded"
              hs.message = condition.message
              return hs
            end
            if condition.type == "Ready" and condition.status == "True" then
              hs.status = "Healthy"
              hs.message = condition.message
              return hs
            end
          end
        end
      end
      hs.status = "Progressing"
      hs.message = "Waiting for certificate"
      return hs
  ```
</Accordion>

## Project

A **Project** provides logical grouping of applications and enables:

* **Multi-tenancy**: Restrict which repositories and clusters teams can use
* **RBAC**: Define who can deploy what and where
* **Resource whitelisting**: Control which Kubernetes resources can be deployed

```yaml theme={null}
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: my-project
  namespace: argocd
spec:
  description: My team's project
  
  # Source repositories that apps can deploy from
  sourceRepos:
    - 'https://github.com/myorg/*'
  
  # Destination clusters and namespaces
  destinations:
    - namespace: 'dev-*'
      server: https://kubernetes.default.svc
    - namespace: 'staging-*'
      server: https://kubernetes.default.svc
  
  # Allowed Kubernetes resources
  clusterResourceWhitelist:
    - group: ''
      kind: Namespace
  namespaceResourceWhitelist:
    - group: 'apps'
      kind: Deployment
    - group: ''
      kind: Service
    - group: ''
      kind: ConfigMap
```

## Configuration Management Plugin

A **Configuration Management Plugin** (CMP) is a custom tool that generates Kubernetes manifests. Use CMPs when built-in tools (Helm, Kustomize, etc.) don't meet your needs.

Example use cases:

* Custom templating engines
* Security scanning integration
* Dynamic manifest generation
* Proprietary configuration tools

## Summary

<Card title="GitOps Workflow">
  1. **Define** your desired state in Git (target state)
  2. **Refresh** to detect differences between Git and cluster (sync status)
  3. **Sync** to apply changes from Git to cluster
  4. **Monitor** health status to ensure application is running correctly
  5. **Repeat** as you make changes to Git
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Architecture" icon="diagram-project" href="/architecture">
    Learn how Argo CD components work together
  </Card>

  <Card title="Automated Sync" icon="rotate" href="https://argo-cd.readthedocs.io/en/stable/user-guide/auto_sync/">
    Enable continuous deployment with auto-sync
  </Card>

  <Card title="Sync Options" icon="sliders" href="https://argo-cd.readthedocs.io/en/stable/user-guide/sync-options/">
    Customize sync behavior with advanced options
  </Card>

  <Card title="Resource Hooks" icon="webhook" href="https://argo-cd.readthedocs.io/en/stable/user-guide/resource_hooks/">
    Execute custom logic during sync lifecycle
  </Card>
</CardGroup>