# Argo CD — Declarative GitOps Continuous Delivery for Kubernetes

> Argo CD is a declarative GitOps CD tool for Kubernetes. Sync applications from Git repositories automatically, with visual diff, rollback, and multi-cluster support.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
# Install Argo CD
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Expose UI
kubectl port-forward svc/argocd-server -n argocd 8080:443

# Get initial admin password
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d
```

Open `https://localhost:8080` — login with admin + password.

## Intro

**Argo CD** is a declarative, GitOps continuous delivery tool for Kubernetes. It continuously monitors Git repositories, detects drift between the desired state (in Git) and the live state (in the cluster), and automatically or manually reconciles the differences. This makes Git the single source of truth for your Kubernetes deployments.

With 22.6K+ GitHub stars and Apache-2.0 license, Argo CD is a CNCF graduated project used by thousands of organizations as the de facto standard for GitOps on 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

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

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

### 3. Login

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

# Login
argocd login localhost:8080
```

### 4. Create First Application

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

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

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

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

```yaml
# 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)

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

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

| Feature | Argo CD | Flux | Jenkins X | Spinnaker |
|---------|---------|------|-----------|-----------|
| GitOps | Yes | Yes | Yes | Hybrid |
| UI | Beautiful | Basic | Yes | Yes |
| Auto-sync | Yes | Yes | Yes | Manual |
| Multi-cluster | Yes | Yes | Yes | Yes |
| App of Apps | Yes | Yes (Kustomize) | No | Pipelines |
| Helm support | Yes | Yes | Yes | Yes |
| Rollback | Git-based | Git-based | Yes | Yes |
| SSO | SAML/OIDC | OIDC | Yes | Yes |

## 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](https://github.com/argoproj/argo-cd) — 22.6K+ ⭐ | Apache-2.0
- Official site: [argo-cd.readthedocs.io](https://argo-cd.readthedocs.io)

---
Source: https://tokrepo.com/en/workflows/argo-cd-declarative-gitops-continuous-delivery-kubernetes-ca164613
Author: AI Open Source