kuncoro.io
Back to shelf

Argo CD

argoproj/argo-cd 18.7k Go

Argo CD Codebase Overview

Argo CD is an open-source, declarative GitOps continuous delivery tool for Kubernetes. It continuously monitors running applications and compares the live state against the desired target state defined in a Git repository, automatically or manually syncing them when drift is detected. A CNCF graduated project, it is the most widely adopted GitOps controller in the Kubernetes ecosystem.

What is this project?

Argo CD (argoproj/argo-cd) implements the GitOps pattern where Git repositories serve as the single source of truth for application definitions and Kubernetes cluster desired state. The system consists of multiple cooperating Go services: an Application Controller that reconciles desired vs. live state, a Repository Server that generates Kubernetes manifests from various sources (Helm, Kustomize, Jsonnet, plain YAML), an API Server exposing REST/gRPC endpoints consumed by the Web UI and CLI, and supporting controllers for ApplicationSets (templated app generation) and notifications.

graph TD
    Git[Git Repository] --> RS[Repo Server<br/>reposerver/]
    RS --> AC[Application Controller<br/>controller/]
    AC --> K8s[Kubernetes Clusters]
    AC --> API[API Server<br/>server/]
    API --> UI[Web UI / CLI]
    API --> AC
    AS[ApplicationSet Controller<br/>applicationset/] --> AC
    NC[Notification Controller<br/>notification_controller/] --> AC
    style AC fill:#f9f,stroke:#333,stroke-width:2px

Why does it exist?

Traditional CD pipelines (Jenkins, Tekton) push changes to clusters imperatively, creating drift between what is defined in Git and what is running. Argo CD inverts this model: it pulls the desired state from Git and continuously reconciles it against the live cluster, detecting and optionally correcting drift automatically. This provides auditability (every change is a Git commit), rollback capability (revert a commit), multi-cluster management (one control plane for many clusters), and self-healing (auto-sync on drift).

Trade-offs: The GitOps model requires all configuration to be declarative and version-controlled, which adds friction for ad-hoc changes. The reconciliation loop introduces latency compared to direct kubectl applies. The multi-component architecture (controller, repo-server, API server, Redis, Dex) has operational overhead compared to simpler CD tools.

Who uses it?

Platform engineers, SREs, and DevOps teams managing Kubernetes workloads at scale. Adopted by organizations including Intuit (original creator), Red Hat (OpenShift GitOps), AWS, and thousands of companies for production deployment management. Use cases:

  • Multi-environment promotion: Dev -> staging -> production via Git branches or directories.
  • Multi-cluster management: Deploy across hundreds of clusters from a single Argo CD instance.
  • Self-service deployments: Developers create Applications via PRs, platform teams control policies via AppProjects.
  • Compliance and auditability: Every deployment is traceable to a Git commit with RBAC enforcement.
  • Drift detection and self-healing: Automatically detect and correct manual cluster changes.

Key Concepts

To dive into the code, master these:

  1. Application CRD: Core abstraction (pkg/apis/application/v1alpha1/types.go). Defines a Source (Git repo + path + revision) and Destination (cluster + namespace). The controller reconciles Spec against live cluster state, updating Status with sync/health information. Supports multiple sources for composite deployments.

  2. Sync and Health Status: Applications have two orthogonal statuses. SyncStatus tracks whether live state matches Git (Synced, OutOfSync). HealthStatus tracks whether resources are functioning (Healthy, Degraded, Progressing). The controller computes both on every reconciliation cycle.

  3. GitOps Engine: The gitops-engine (embedded as a Go module) provides the diff/sync primitives. It maintains an in-memory cache of cluster resources, computes three-way merge diffs, and applies changes with sync waves and hooks (PreSync, Sync, PostSync).

  4. AppProject: Multi-tenancy boundary (pkg/apis/application/v1alpha1/types.go). Restricts which repos, clusters, namespaces, and resource kinds an Application can use. Enforces RBAC via Casbin policies. Every Application belongs to a project (default: default).

  5. ApplicationSet: Template-based Application generator (applicationset/). Uses generators (Git directory, cluster list, PR events, matrix/merge combinators) to dynamically create Applications from a single template. Enables patterns like “deploy to every cluster” or “create app per directory”.

Project Structure

The monorepo is organized around services, with shared packages in pkg/ and util/:

argoproj/argo-cd/
├── cmd/                    # Binary entry points (cobra CLI)
│   ├── argocd/             # CLI tool
│   ├── argocd-server/      # API server
│   ├── argocd-application-controller/  # Core controller
│   ├── argocd-repo-server/ # Manifest generation
│   └── ...                 # notification, appset, cmp, dex
├── controller/             # Application controller logic
│   ├── appcontroller.go    # Main reconciliation loop
│   ├── state.go            # App state comparison
│   ├── sync.go             # Sync operation execution
│   └── sharding/           # Multi-replica distribution
├── reposerver/             # Manifest generation service
│   ├── server.go           # gRPC server setup
│   └── repository/         # Git/Helm/Kustomize generation
├── server/                 # API server
│   ├── server.go           # HTTP/gRPC multiplexer
│   ├── application/        # App CRUD handlers
│   ├── cluster/            # Cluster management
│   └── session/            # Auth/JWT
├── applicationset/         # ApplicationSet controller
├── notification_controller/# Notification engine
├── gitops-engine/          # Diff/sync/health engine (submodule)
├── pkg/apis/               # CRD type definitions
├── util/                   # Shared utilities
└── ui/                     # React Web UI

Clever patterns:

  • Multi-binary dispatch: A single cmd/main.go dispatches to the correct component based on binary name (via symlinks or build tags), simplifying Docker image construction.
  • gitops-engine as embedded module: Core diff/sync logic lives in its own Go module for reuse by other GitOps tools, while being developed alongside Argo CD.
  • Resource customizations: The resource_customizations/ directory contains per-resource health checks and actions as Lua scripts, making health assessment extensible without recompilation.

Start with controller/appcontroller.go for the reconciliation loop, then reposerver/repository/ for manifest generation, then server/ for the API layer.