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

Basic Application

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

Application Source Type

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

Plain Kubernetes Manifests

Raw YAML/JSON files in a directory

Helm

Helm charts from Git repos or Helm registries

Kustomize

Kustomize overlays and bases

Jsonnet

Jsonnet files with external variables

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

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.

# 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.

# 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?”

Synced

Live state matches target state

OutOfSync

Live state differs from target state

Unknown

Unable to determine sync status

Viewing Sync Status

# 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

# 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:

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.

# Refresh the application state
argocd app get guestbook --refresh

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

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

Health Status

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

Healthy

All resources are healthy and ready

Progressing

Resources are being created or updated

Degraded

One or more resources are unhealthy

Suspended

Application is suspended (e.g., CronJob)

Missing

Resources don’t exist in the cluster

Unknown

Health status cannot be determined

Health Assessment

Argo CD determines health based on resource type:

Deployment: All replicas are ready

status:
  availableReplicas: 3
  replicas: 3
  readyReplicas: 3

Service: Endpoints exist (for non-headless services)

Pod: All containers running and ready

Job: Job completed successfully

Custom Health Checks

You can define custom health checks for CRDs in the argocd-cm ConfigMap:

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

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

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

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

Next Steps

Architecture

Learn how Argo CD components work together

Automated Sync

Enable continuous deployment with auto-sync

Sync Options

Customize sync behavior with advanced options

Resource Hooks

Execute custom logic during sync lifecycle