Skip to main content

​
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
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
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

Build docs developers (and LLMs) love

Get started for freeTalk to us