Skip to content

ArgoCD — How It Works

Reconciliation engine, sync phases, ApplicationSet generators, and drift detection.

Reconciliation Loop

sequenceDiagram
    participant Git as Git Repository
    participant RepoSvr as Repository Server
    participant AppCtrl as Application Controller
    participant Cluster as Target Cluster

    loop Every 3 minutes (configurable)
        AppCtrl->>RepoSvr: Fetch latest manifests
        RepoSvr->>Git: git clone/pull (or cached)
        RepoSvr->>RepoSvr: Render: Helm template / Kustomize build
        RepoSvr-->>AppCtrl: Desired state (manifests)
        AppCtrl->>Cluster: Get live state (kubectl get)
        AppCtrl->>AppCtrl: Diff: desired vs live
        alt Drift detected
            AppCtrl->>AppCtrl: Mark: OutOfSync
            alt Auto-sync enabled
                AppCtrl->>Cluster: Apply manifests (kubectl apply)
            end
        else No drift
            AppCtrl->>AppCtrl: Mark: Synced ✓
        end
    end

Sync Waves & Hooks

flowchart LR
    PreSync["PreSync\n(DB migrations, \nconfig setup)"] --> Sync["Sync\n(main resources)"] --> PostSync["PostSync\n(smoke tests,\nnotifications)"]
    PreSync -.->|"Wave 0"| NS["Namespace"]
    PreSync -.->|"Wave 1"| CM["ConfigMaps"]
    Sync -.->|"Wave 2"| Deploy["Deployments"]
    Sync -.->|"Wave 3"| SVC["Services"]
    PostSync -.->|"Wave 4"| Test["Test Jobs"]

    style PreSync fill:#e65100,color:#fff
    style Sync fill:#1565c0,color:#fff
    style PostSync fill:#2e7d32,color:#fff

ApplicationSet Generators

Generator Use Case
Git Directory One app per directory in monorepo
Git File Config-driven from JSON/YAML in Git
Cluster Deploy same app to all registered clusters
List Static list of environments
Matrix Cross-product of two generators
Merge Combine multiple generators
Pull Request Preview environments per PR
SCM Provider Auto-discover repos from GitHub/GitLab org

Sources