English for Argo CD

Argo CD is built around a single principle — Git is the source of truth for what should be running in a cluster — and most of its vocabulary describes how it detects and resolves the gap between that intent and reality.

Key Vocabulary

GitOps — the practice of using a Git repository as the single source of truth for a system’s desired state, with an automated tool like Argo CD continuously reconciling the live cluster to match what’s declared in Git. “We’re following GitOps here, which means nobody should be running kubectl apply manually against production — every change goes through a pull request to the Git repo, and Argo CD picks it up and applies it.”

Sync — the act of Argo CD applying the state declared in Git to the actual Kubernetes cluster, either triggered automatically on a Git change or manually initiated, bringing the live state in line with the desired state. “The deployment isn’t live yet because auto-sync is disabled on this application — someone needs to trigger a manual sync in the Argo CD UI, or enable auto-sync so future Git changes apply automatically.”

Drift — a difference between what’s declared in Git and what’s actually running in the cluster, typically caused by someone making a manual change directly against the cluster instead of through Git. “Argo CD is flagging drift on this deployment — someone scaled the replica count manually with kubectl, but Git still says three replicas, so the two are now out of sync until someone reconciles them.”

Application manifest — the Argo CD resource definition describing what to deploy, from which Git repository and path, and how to sync it, essentially telling Argo CD which piece of Git it’s responsible for reconciling. “We need a new application manifest for this service — it tells Argo CD which Git path holds its Kubernetes manifests and which cluster and namespace to deploy them into.”

Self-heal — an Argo CD setting that automatically reverts drift by re-syncing whenever it detects the live cluster state has diverged from Git, enforcing Git as the actual source of truth rather than just a suggestion. “With self-heal enabled, that manual kubectl edit someone made got reverted within a minute — Argo CD noticed the drift and automatically re-synced the cluster back to match what’s declared in Git.”

Common Phrases

• “Are we actually following GitOps here, or is someone still applying changes manually?”
• “Does this application need a manual sync, or is auto-sync enabled?”
• “Is Argo CD flagging drift on this deployment right now?”
• “Does this service have an application manifest set up yet?”
• “Should self-heal be enabled here, or do we want manual control over reconciliation?”

Example Sentences

Explaining the deployment model: “Under GitOps, the only way to change what’s running in production is a pull request against the manifests repo — Argo CD sees the merge and syncs the cluster automatically, there’s no direct kubectl access to production for anyone.”

Diagnosing an incident: “The dashboard shows this deployment out of sync because of drift — someone made an emergency manual change during the incident, which is understandable, but we need to update Git to match, or trigger a sync to revert it, so the two don’t stay diverged.”

Justifying a configuration choice: “We’re leaving self-heal off for this particular application, on purpose — it’s a stateful service where we sometimes need to make careful manual interventions, and we don’t want Argo CD reverting those before we’re done.”

Professional Tips

• Enforce GitOps as a real practice, not just a tool choice — direct manual changes against the cluster undermine the entire value proposition, since Git stops being trustworthy as the source of truth.
• Understand the difference between automatic and manual sync before enabling it broadly — auto-sync is convenient but means every merged Git change goes live immediately.
• Treat drift alerts as signals worth investigating, not noise to dismiss — they usually indicate either an emergency manual fix that needs to be reflected in Git, or an unauthorized change.
• Keep each application manifest scoped to one deployable unit — overly broad manifests make it harder to reason about what a given sync will actually change.
• Use self-heal for stateless, low-risk services where automatic drift correction is safe, but consider disabling it for stateful services where manual intervention sometimes needs to persist temporarily.

Practice Exercise

1. Explain what “GitOps” means and how Argo CD enforces it.
2. Describe a scenario that would cause Argo CD to report drift.
3. Write a sentence explaining the tradeoff of enabling self-heal on a stateful service.