# 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 in your project root:

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

## 常见问题

**Q: Argo CD 和 Flux 怎么选？**
A: Argo CD 有更强大的 Web UI 和可视化功能，适合需要直观查看集群状态的团队。Flux 更轻量，完全符合 GitOps 原则（无 UI 操作按钮，所有变更通过 Git）。两者都是 CNCF 项目，功能相当。

**Q: 可以管理多少个集群？**
A: 单个 Argo CD 实例可以管理数百个集群。通过 ApplicationSet，可以将相同的应用自动部署到所有符合条件的集群（如所有 dev 集群或所有区域集群）。

**Q: 部署失败如何回滚？**
A: 两种方式：1）在 UI 中选择历史 revision 并同步；2）在 Git 中 revert commit，Argo CD 自动同步回滚。推荐使用 Git revert，保持 GitOps 原则。

## 来源与致谢

- GitHub: [argoproj/argo-cd](https://github.com/argoproj/argo-cd) — 22.6K+ ⭐ | Apache-2.0
- 官网: [argo-cd.readthedocs.io](https://argo-cd.readthedocs.io)

---
Source: https://tokrepo.com/en/workflows/ca164613-353d-11f1-9bc6-00163e2b0d79
Author: AI Open Source