Argo CD: Git as the Source of Truth for Kubernetes

Why it exists

Managing Kubernetes manifests manually across different environments is complex and error-prone. Using kubectl apply directly offers no clear audit trail, versioning, or a single source of truth for what should be running. This makes rollbacks difficult and configuration drift between environments almost inevitable.

The mental model

Think of Argo CD as a security guard for your Kubernetes cluster. It holds a photo of what the cluster should look like (your Git repo) and constantly patrols the grounds (the live cluster). If it sees anything out of place, like a manual change made with kubectl, it raises an alarm by marking the application as "OutOfSync." It can then be configured to automatically restore the cluster to match the state in the photo.

How it works

Argo CD runs as a controller inside your Kubernetes cluster. You define an "Application" custom resource that tells Argo CD two things: where your configuration lives (a Git repository, path, and revision) and where to deploy it (a destination cluster and namespace). Argo CD then continuously fetches the latest manifests from your Git source, compares them to the live resources in the destination cluster, and reports the difference. If you enable auto-sync, it will automatically apply the changes from Git to the cluster to eliminate any drift.

When to use it

Use Argo CD when you want to adopt a GitOps workflow for Kubernetes. It is excellent for managing application deployments, ensuring environment consistency (dev, staging, prod), and providing a clear, auditable history of all changes to your cluster's state. It natively supports plain YAML manifests, Kustomize, Helm charts, and Jsonnet.

When not to use it

Argo CD is a Continuous Delivery (CD) tool, not a Continuous Integration (CI) tool. It does not build your container images or run your tests; it only deploys what's already defined in Git. For a full build-test-deploy pipeline, you must pair Argo CD with a CI system like GitHub Actions or Jenkins. Avoid it if your team is not prepared to commit to Git as the exclusive source of truth.

One canonical example

A team manages a microservice's deployment.yaml in a Git repository. To update the image tag, a developer opens a pull request to change image: my-app:v1 to image: my-app:v2. Once merged to the main branch, Argo CD detects the change, shows the application as "OutOfSync," and automatically applies the new manifest. This triggers a rolling update of the deployment in the Kubernetes cluster. The entire change is visible, auditable, and reversible in Git history.