Understanding Argo CD: GitOps Workflow and Core Principles

Argo CD is a declarative, GitOps-based continuous delivery (CD) tool for Kubernetes. This article skips installation steps and instead explains how Argo CD works, why its control loop is reliable, and how GitOps reshapes deployment governance.

1. GitOps as an Engineering System

GitOps is not just “store YAML in Git.” It turns deployment into a governed engineering process:

  • Declarative and reviewable: desired state is readable, testable, and reproducible.
  • Change process = audit process: PR approvals are release approvals.
  • Continuous reconciliation: drift is detected and corrected over time.
  • Rollback by Git: reverting commits restores previous states.

This shifts delivery from “execution” to “continuous configuration management.”

1.1 Additional GitOps Principles

Beyond the basics, GitOps emphasizes:

  • Unidirectional change flow: runtime state must only derive from Git, not manual cluster edits, preserving auditability.
  • Verifiable desired state: configurations should be linted, policy-checked, and tested before promotion.
  • Least privilege and clear boundaries: controllers reconcile inside the cluster, reducing external write exposure.
  • Immutable delivery trail: build-to-deploy inputs remain traceable, avoiding hidden “hot fixes.”

These principles elevate GitOps from a deployment method to a governance model.

2. Pull-Based Delivery Model

Traditional CD pushes manifests into clusters. Argo CD uses a pull-based model:

  • Controllers inside the cluster pull desired state from Git.
  • Git becomes the authoritative entry point for changes.

Benefits include:

  • Security: CI does not require high-privilege cluster write access.
  • Consistency: cluster state converges toward Git state.
  • Governance: policies are enforced inside the cluster boundary.

3. Architecture and Core Components

Argo CD consists of:

  1. API Server

    • UI/CLI/Webhook entry point.
    • Authentication, authorization, and app management APIs.

  2. Repository Server

    • Fetches Git repositories and renders manifests.
    • Supports Helm, Kustomize, Jsonnet, and plain YAML.
    • Caches render results to speed up diffs.

  3. Application Controller

    • Reconciliation engine that compares desired and live state.
    • Triggers syncs, drift correction, and health evaluation.

  4. Dex / OIDC (optional)

    • Integrates external identity providers for SSO.

3.1 Reconciliation Loop

The control loop mirrors Kubernetes patterns:

  1. Git changes (or polling) are detected.
  2. Repo Server renders manifests.
  3. Controller fetches live cluster state.
  4. Diffs are computed, updating status (Synced/OutOfSync).
  5. Sync policy decides whether to apply changes.

Argo CD is therefore a state convergence system, not a script runner.

4. Application CRD: Declarative Governance

Argo CD models apps with the Application CRD:

  • source: repo URL, path, and render method.
  • destination: target cluster and namespace.
  • syncPolicy: auto or manual sync.
  • syncOptions: pruning, namespace creation, replace behavior.

4.1 App-of-Apps Pattern

  • A root app points to a directory of Application manifests.
  • Child apps sync independently and scale by team ownership.

4.2 ApplicationSet

ApplicationSet generates Applications from templates:

  • Use Git directories, cluster lists, or PRs as generators.
  • Ideal for multi-tenant or multi-cluster fleet management.

5. Diff Semantics and Drift Detection

Argo CD continuously compares desired and live state:

  • Diff: difference between Git and cluster state.
  • Drift: cluster mutations outside Git control.

Common drift sources:

  • Manual kubectl apply changes.
  • Autoscalers modifying replicas.
  • Operators mutating resources.

To reduce noise:

  • ignoreDifferences can ignore specific fields.
  • Resource customizations adjust health and diff rules.

6. Sync Semantics and Execution Details

6.1 Sync Modes

  • Manual sync: safer for production with approvals.
  • Auto sync: suitable for dev/test or high-frequency pipelines.

6.2 Sync Behaviors

Sync is more than apply:

  • Pruning: delete resources removed from Git.
  • Sync Waves: order resources to respect dependencies.
  • Hooks: PreSync/Sync/PostSync jobs for migrations or checks.
  • Replace vs Apply: handle immutable fields or destructive updates.

6.3 Self-Heal

Auto-sync enables continuous restoration of drifted resources.

6.4 Resource Health Evaluation

Health checks determine readiness:

  • Deployment/StatefulSet availability.
  • Job completion status.
  • Custom CRD health definitions.

Health directly influences sync outcomes and automation decisions.

7. GitOps Workflow: Change to Delivery

A typical flow:

  1. Developer submits a PR/MR.
  2. After approval, Argo CD fetches updates.
  3. Manifests are rendered and compared to live state.
  4. Sync is triggered (manual or auto).
  5. Monitoring systems provide feedback.

Key concept:

  • Git history = audit trail.
  • PR approvals = release approvals.

8. Multi-Environment and Multi-Cluster Strategies

Common patterns:

  • Environment branches: dev/staging/prod.
  • Directory structure: env-specific folders in one branch.
  • Parameterized rendering: Helm values or Kustomize overlays.

8.1 Promotion Workflows

A common approach is promotion via Git:

  • Validate in dev, then promote commits to staging/prod.
  • Each promotion is a Git commit, preserving auditability.

9. Image Updates and GitOps Automation

Argo CD does not build images. Typical automation:

  • CI builds images → updates Git with new tags.
  • Or use Argo CD Image Updater to commit version bumps.

The invariant is: all changes must land in Git.

10. Security and Multi-Tenancy Governance

Argo CD security includes:

  • RBAC: role-based access control.
  • Projects: isolate teams, repos, and namespaces.
  • Repo credentials: manage Git access securely.
  • Cluster credentials: secure multi-cluster access.

Projects are essential for enforcing boundaries in large organizations.

11. Observability and Eventing

Argo CD provides:

  • Topology views for dependency visualization.
  • Audit logs for sync events.
  • Events and status for failure analysis.
  • Notifications to Slack/email/Webhooks.

This enables a full delivery feedback loop when combined with monitoring systems.

12. Progressive Delivery Integration

Argo CD manages desired state, while progressive delivery (canary/blue-green) is typically handled by:

  • Argo Rollouts or service meshes.
  • Argo CD remains responsible for desired state and rollback triggers.

This separation keeps Argo CD focused on reconciliation, not traffic routing.

13. Common Pitfalls and Boundaries

  • Treating Argo CD as a script runner: it is a control loop.
  • Manual cluster edits: break GitOps consistency.
  • Ignoring immutable fields: requires replace or re-create strategies.
  • Over-automating production: manual approvals often reduce risk.

14. Summary

Argo CD makes Git the single source of truth and continuously reconciles cluster state. When combined with GitOps workflows, promotion strategies, and governance controls, it delivers auditable, repeatable, and scalable delivery across environments.