Argo CD: GitOps Delivery for Kubernetes

Argo CD

Argo CD is a declarative continuous delivery tool for Kubernetes built around GitOps: the desired state of every application lives in Git, and Argo CD continuously compares it with what is running in clusters, shows the differences, and syncs them — automatically or on approval. Changes go through pull requests, every deployment is a commit, rollbacks are reverts, and manual changes to the cluster show up as drift. Argo CD is a CNCF graduated project and one of the most common ways to run Kubernetes deployments at scale.

Getting started takes minutes. Running it well across many teams and clusters requires decisions about access boundaries, promotion between environments, secrets, and how to recover Argo CD itself when something goes wrong.

TL;DR

An Application maps a Git source (Helm, Kustomize, plain manifests) to a destination cluster and namespace.
Sync policies can apply changes automatically, prune removed resources, and self-heal drift.
Health checks, diffing, sync waves, and hooks control rollout order and status.
ApplicationSets generate Applications for many clusters, environments, or directories.
Projects (AppProjects) restrict which repositories, clusters, namespaces, and resource kinds each team may use; combine with SSO and RBAC.
Keep Argo CD's own configuration in Git, handle secrets with dedicated tools, and practice disaster recovery.

Quick Example

An Application that keeps the production overlay of a service in sync and heals drift:

A Project that limits the team to its own repository and namespace, with no cluster-scoped resources:

Core Concepts

Applications and Sources

An Application declares where manifests come from — a Git repository path, Helm chart, or OCI artifact, rendered with Helm, Kustomize, or plain YAML — and where they go — a cluster and namespace. Argo CD renders the manifests, compares them with live resources, and reports each Application as Synced or OutOfSync and Healthy, Progressing, or Degraded.

Sync Policies and Drift

Self-heal makes Git the only way to change an application, which is the point of GitOps — but configure ignoreDifferences for fields legitimately changed at runtime.

Sync Waves and Hooks

Sync waves (annotations with integer order) apply resources in phases — CRDs and namespaces before workloads, migrations before new versions. Hooks run Jobs at PreSync, Sync, PostSync, or SyncFail, for database migrations or smoke tests. Health checks (built in, or custom in Lua) decide when each wave is ready.

ApplicationSets and App of Apps

ApplicationSets generate many Applications from templates and generators: lists, registered clusters, Git directories or files, pull requests, and combinations (matrix, merge). The app-of-apps pattern uses one Application that deploys other Application manifests. Both keep large fleets manageable.

Projects, SSO, and RBAC

AppProjects are the main access boundary: allowed source repositories, destination clusters and namespaces, permitted resource kinds (especially cluster-scoped ones), and project roles. SSO through OIDC providers or Dex maps identity-provider groups to Argo CD RBAC policies. Keep the default project locked down, and remember that anyone who can sync an Application can deploy whatever its source contains. See Kubernetes RBAC.

Secrets

Git should never contain plaintext secrets. Common approaches:

External Secrets Operator: manifests reference secrets stored in a secrets manager, synced into the cluster.
Sealed Secrets or SOPS: encrypted secrets in Git, decrypted in the cluster or during rendering.
CSI secrets drivers: mount secrets from external stores directly into pods.

See Secrets Management.

Promotion Between Environments

GitOps makes promotion a change in Git: update the image tag or chart version in the staging overlay, verify, then open a pull request for production. Teams automate this with CI that commits version bumps, image-update tooling, or dedicated promotion tools. Keep environments in separate directories or overlays rather than separate long-lived branches, which drift apart. See Deployment Strategies.

Operating Argo CD

Manage Argo CD with Argo CD: its configuration, projects, and Applications live in Git.
High availability: run the HA manifests for controllers, repo servers, and Redis in production.
Scale: shard the application controller across clusters and tune repo server resources for large repositories.
Notifications: send sync failures and degraded health to chat or incident tools.
Disaster recovery: back up Argo CD state (argocd admin export), cluster credentials, and any encryption keys for secrets; rehearse restoring Argo CD and resyncing applications into a new cluster.

Best Practices

Keep Git the Only Write Path

Use automated sync with self-heal for production, restrict direct kubectl access, and treat drift alerts as incidents.

Model Access With Projects

Give each team a Project with only its repositories, namespaces, and resource kinds, and keep cluster-scoped resources with the platform team.

Separate Configuration From Application Code

Store deployment manifests in a dedicated repository or directory, so deploys do not require rebuilding application code and history stays readable.

Order Rollouts Explicitly

Use sync waves for dependencies and hooks for migrations and smoke tests, rather than relying on retry loops.

Common Mistakes

Fighting Other Controllers

Everything in the Default Project

Plaintext Secrets in Git

FAQ

What is Argo CD?

A GitOps continuous delivery tool for Kubernetes that continuously compares application manifests stored in Git with the live state of clusters and syncs them, providing visibility into drift, health, and history.

What is the difference between Argo CD and Argo Workflows?

Argo CD handles continuous delivery of Kubernetes manifests from Git. Argo Workflows runs containerized workflows and pipelines as directed graphs. They are separate projects in the Argo family.

How does Argo CD handle drift?

It marks Applications as out of sync when live resources differ from Git. With self-heal enabled, it automatically reverts the differences to match Git.

What are ApplicationSets?

A controller and resource that generate many Argo CD Applications from a template and generators — such as lists, clusters, Git directories, or pull requests — for managing fleets of applications and environments.

How should secrets be handled with Argo CD?

Keep plaintext secrets out of Git. Use the External Secrets Operator to sync from a secrets manager, or encrypted secrets with Sealed Secrets or SOPS that are decrypted in the cluster.