Argo CD — Declarative GitOps Continuous Delivery for Kubernetes

What Argo CD Does

• GitOps: Git is the source of truth for cluster state
• Auto-Sync: Automatically apply changes when Git is updated
• Diff View: Visual comparison between Git and live cluster state
• Rollback: One-click rollback to any previous Git commit
• Multi-Cluster: Deploy to multiple Kubernetes clusters from one Argo CD
• Multi-Source: Combine Helm, Kustomize, Jsonnet, plain YAML in one app
• App of Apps: Define applications that create other applications
• Health Status: Real-time health monitoring of deployed resources
• SSO: Integration with Dex, OIDC, SAML, LDAP, GitHub, GitLab, Google
• RBAC: Fine-grained permissions for users and teams
• Webhooks: Trigger sync from Git provider webhooks
• Notifications: Slack, email, webhook notifications on events

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Git Repo    │────▶│  Argo CD     │────▶│  Kubernetes  │
│  (Source of  │     │  Controller  │     │  Cluster(s)  │
│   Truth)     │     │              │     │              │
└──────────────┘     └──────┬───────┘     └──────────────┘
                            │
                     ┌──────┴───────┐
                     │  Argo CD UI  │
                     │  + CLI + API │
                     └──────────────┘

Getting Started

1. Install Argo CD

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Or via Helm
helm repo add argo https://argoproj.github.io/argo-helm
helm install argocd argo/argo-cd --namespace argocd --create-namespace

2. Install CLI

brew install argocd
# Or download from https://github.com/argoproj/argo-cd/releases

3. Login

# Get initial password
argocd admin initial-password -n argocd

# Login
argocd login localhost:8080

4. Create First Application

argocd app create guestbook 
  --repo https://github.com/argoproj/argocd-example-apps.git 
  --path guestbook 
  --dest-server https://kubernetes.default.svc 
  --dest-namespace default

Or via YAML:

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
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Key Features

Application Types

# Plain YAML manifests
source:
  repoURL: https://github.com/org/manifests.git
  path: apps/myapp

# Helm chart
source:
  repoURL: https://charts.bitnami.com/bitnami
  chart: postgresql
  targetRevision: 12.5.3
  helm:
    values: |
      auth:
        postgresPassword: secret
      primary:
        persistence:
          size: 10Gi

# Kustomize
source:
  repoURL: https://github.com/org/manifests.git
  path: overlays/production
  kustomize:
    namePrefix: prod-
    images:
      - myapp=myregistry/myapp:v2.0.0

# Jsonnet
source:
  repoURL: https://github.com/org/manifests.git
  path: jsonnet
  directory:
    jsonnet:
      extVars:
        - name: environment
          value: production

Sync Policies

syncPolicy:
  automated:
    prune: true       # Delete resources removed from Git
    selfHeal: true    # Revert manual changes
    allowEmpty: false # Don't sync if target is empty

  syncOptions:
    - CreateNamespace=true
    - PruneLast=true
    - ServerSideApply=true

  retry:
    limit: 5
    backoff:
      duration: 5s
      factor: 2
      maxDuration: 3m

App of Apps Pattern

# Parent app that creates other apps
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: all-apps
spec:
  source:
    repoURL: https://github.com/org/gitops.git
    path: apps           # Directory with app definitions
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true

Directory structure:
gitops/
├── apps/              ← App of Apps watches this
│   ├── frontend.yaml  ← Defines Application for frontend
│   ├── backend.yaml   ← Defines Application for backend
│   └── database.yaml  ← Defines Application for database
└── manifests/
    ├── frontend/
    ├── backend/
    └── database/

ApplicationSet (Multi-Cluster)

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapp-to-all-clusters
spec:
  generators:
    - clusters: {}  # Deploy to all registered clusters
  template:
    metadata:
      name: 'myapp-{{name}}'
    spec:
      source:
        repoURL: https://github.com/org/manifests.git
        path: apps/myapp
      destination:
        server: '{{server}}'
        namespace: myapp

Health Checks & Sync Waves

# Control ordering of resources
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "1"  # Apply first
    argocd.argoproj.io/hook: PreSync    # Run before sync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded

Argo CD vs Alternatives

FAQ

Q: Argo CD or Flux — which should I choose? A: Argo CD has a more powerful Web UI and visualization, great for teams that want to see cluster state at a glance. Flux is more lightweight and strictly GitOps (no UI action buttons — all changes go through Git). Both are CNCF projects with comparable capabilities.

Q: How many clusters can it manage? A: A single Argo CD instance can manage hundreds of clusters. With ApplicationSet, the same application can be automatically deployed to all matching clusters (e.g., all dev clusters or all regional clusters).

Q: How do I roll back a failed deployment? A: Two ways: 1) pick a historical revision in the UI and sync; 2) revert the commit in Git and let Argo CD auto-sync the rollback. Git revert is preferred — it keeps the GitOps principle intact.

Sources & Credits

• GitHub: argoproj/argo-cd — 22.6K+ ⭐ | Apache-2.0
• Official site: argo-cd.readthedocs.io