GitOps Vocabulary

Drift detection is automatic in Argo CD; auto-remediation (sync) is opt-in per Application.

Argo CD sync modes:

Mode	Behaviour on drift	When to use
Manual sync (default)	Reports OutOfSync; waits for operator to click "Sync" or run argocd app sync	Production environments where human approval is required before changes
Auto-sync	Automatically applies a sync within seconds of detecting drift	Dev/staging environments; or production with high confidence in CI pipeline guardrails
Auto-sync + self-heal	Also automatically reverts any manual changes made to the cluster outside of Git	Strict GitOps environments where the cluster must always exactly match Git

The drift detection cycle:

Every 3 minutes (default):
  1. Fetch latest commit from Git repo
  2. Render manifests (Helm render, Kustomize build, plain YAML)
  3. Compare rendered manifests with live cluster state
  4. If difference found → mark as OutOfSync
  5. If auto-sync enabled → trigger sync (apply manifests to cluster)

Key vocabulary:
• Desired state — the configuration declared in the Git repository (the source of truth)
• Observed state — the actual live configuration of resources in the Kubernetes cluster
• Drift — any divergence between desired state and observed state
• Sync — the Argo CD operation that applies manifests to bring the cluster into alignment with Git
• OutOfSync — Argo CD's status label when drift is detected
• Self-heal — an Argo CD option that automatically reverts manual cluster changes that deviate from Git

Reconciliation means actively closing the gap — not just detecting or reporting it.

Reconciliation in practice:

Scenario	Desired (Git)	Observed (cluster)	Reconciliation action
Replicas drifted	replicas: 3	replicas: 2	Scale up: create 1 pod
New resource added to Git	ConfigMap present	ConfigMap missing	Create ConfigMap
Resource removed from Git	Service absent	Service exists	Delete Service (if pruning enabled)
Manual change on cluster	image: app:1.4.0	image: app:1.5.0 (manual)	Revert to app:1.4.0 (with self-heal)

The reconciliation loop is the core of GitOps reliability:
• Continuous — runs on a schedule (Argo CD: every 3 min default) and on Git commit webhooks
• Idempotent — running the same sync multiple times produces no additional changes if already converged
• Eventually consistent — the cluster converges to the desired state; transient failures are retried

Kubernetes controllers also use reconciliation:
The same pattern appears in every Kubernetes controller: the ReplicaSet controller reconciles pod count; the Deployment controller reconciles rollout state. GitOps operators apply the same model at the application configuration level.

Key vocabulary:
• Reconciliation loop — a continuous compare-and-act cycle that converges actual state toward desired state
• Pruning — the GitOps option to delete cluster resources that no longer appear in the Git repository
• Convergence — the eventual alignment of observed state with desired state after reconciliation
• Eventually consistent — a system property where state convergence is guaranteed but may not be instantaneous

In a push model, your CI/CD pipeline needs a kubeconfig with cluster-admin permissions stored as a secret — a significant blast radius if that secret is compromised.

Push model security profile:

CI server (external) ──── kubeconfig secret ────► kubectl apply ──► cluster
                          ↑ If leaked: full cluster access from the internet

Pull model security profile:

Git repo (external) ◄──── Argo CD operator (inside cluster) reads Git
                          Cluster never exposes kubectl API to external systems
                          Only outbound read access to Git is needed

Security benefits of the pull model:

Concern	Push model	Pull model (GitOps)
Credential exposure	Kubeconfig stored in CI secrets; accessible by CI admins and pipeline scripts	No external credentials needed; only Git read access from inside cluster
Cluster API exposure	Kubernetes API must be reachable from CI runners (internet or VPN)	Kubernetes API can be private; only internal operator needs access
Blast radius	Compromised CI = cluster access	Compromised CI = can only push to Git (still needs PR approval)
Audit trail	Pipeline logs; hard to trace who approved what	Every deployment is a Git commit with a PR author and reviewer

Key vocabulary:
• Pull model — the in-cluster GitOps operator pulls configuration from Git; no external system pushes to the cluster
• Push model — a CI/CD pipeline pushes changes directly to the cluster using stored credentials
• Blast radius — the scope of damage that can result if a security credential or system is compromised
• Kubeconfig — a file containing cluster endpoint, authentication credentials, and context for kubectl access

When Argo CD manages a Helm chart, it renders the templates and applies them to the cluster — but it does not preserve Helm's release versioning model.

Standalone Helm release lifecycle:

helm install myapp ./chart     → creates release revision 1
helm upgrade myapp ./chart     → creates release revision 2
helm rollback myapp 1          → applies revision 1 manifests from Helm's history

Argo CD-managed Helm chart:

Argo CD renders chart + applies manifests → cluster state matches Git
helm history myapp             → shows revisions, but Argo CD manages them
helm rollback myapp 1          → may conflict with Argo CD's desired state; 
                                  will be overwritten at next sync

GitOps rollback process:

Approach	Steps
Standalone Helm	helm rollback myapp 2 — Helm applies the previous revision's manifests immediately
Argo CD + Helm	git revert HEAD~1 → push → Argo CD detects new commit → syncs cluster to reverted state

Why this matters in practice:
• helm rollback on an Argo CD-managed release creates a temporary divergence; Argo CD will detect it as drift and re-sync back to the Git state on the next reconciliation loop — effectively undoing the helm rollback
• In GitOps, Git is the single source of truth; any out-of-band changes (including helm rollback) are treated as drift and eventually overwritten

Key vocabulary:
• Helm release history — Helm's versioned record of each install/upgrade, stored as Secrets in the cluster; enables helm rollback
• Argo CD sync — Argo CD's apply of Git-rendered manifests to the cluster; does not create or update Helm release history entries
• Out-of-band change — a modification to the cluster made outside the GitOps pipeline (kubectl, helm CLI); treated as drift and reconciled away

The App of Apps pattern applies GitOps discipline to the application registry itself — the fleet of Argo CD Application resources becomes a GitOps-managed artifact.

The problem without App of Apps:

Adding a new service:
  → log into Argo CD UI → click "New App" → configure 12 fields → save
  → no Git record of who created it, what options were set, or when
  → to recreate the Argo CD setup after a disaster: repeat manually 40 times

With App of Apps:

Git repo:
  apps/
    parent-app.yaml      ← Argo CD Application that points to this directory
    services/
      payments.yaml      ← Argo CD Application resource for payments service
      orders.yaml        ← Argo CD Application resource for orders service
      ...                ← 40 Application manifests, all in Git

Adding a new service: create PR adding new-service.yaml → merge → Argo CD
parent app reconciles → creates the new Application → syncs the service

Benefits of App of Apps:

Benefit	Details
GitOps for Argo CD itself	Application definitions are versioned, reviewable, and auditable commits
Disaster recovery	Rebuild all 40 Applications on a new cluster: kubectl apply -f parent-app.yaml
Onboarding automation	New service onboarding is a PR; no Argo CD admin access required
Consistent configuration	ApplicationSet (the evolution of App of Apps) generates Applications from a template — no per-app configuration drift

Key vocabulary:
• App of Apps — an Argo CD pattern where a parent Application manages child Application resources, bringing the application registry under GitOps control
• ApplicationSet — a newer Argo CD resource that generates multiple Application resources from a template and a generator (git directory, cluster list, etc.)
• Fleet management — operating and governing a large number of Kubernetes applications or clusters from a central control plane