Argo CD

Argo CD is a declarative continuous delivery tool for Kubernetes. It watches application definitions, compares their desired resources with live cluster resources, and reports or corrects the differences.

The central mental model is a control loop between Git and Kubernetes.

Git revision
     |
     v
rendered manifests ---- compare ---- live cluster
         |                               |
         +------ Application status -----+
                         |
                    manual or automated sync

You do not give Argo CD a deployment script. You give it an Application that names a source, a revision, a path or chart, and a destination. Argo CD renders the source into Kubernetes manifests. Its application controller then compares those manifests with the resources in the destination cluster.

That comparison produces two distinct signals:

sync status tells you whether live state matches target state;
health status tells you whether the live resources appear able to serve their purpose.

An Application can be Synced but unhealthy. The cluster may contain exactly the requested Deployment while its Pods fail to become ready. It can also be OutOfSync but healthy. The existing workload may still serve traffic while Git describes a newer version.

Why Argo CD exists

A conventional deployment pipeline often builds an artifact and pushes manifests into a cluster. The pipeline needs cluster credentials, and its job usually ends after one apply operation.

Argo CD separates those responsibilities. Your build system still tests code and produces artifacts. A configuration change then records the intended deployment in Git. Argo CD runs beside the target environment and continuously compares that intent with the cluster.

This design gives you:

a version-controlled declaration of application state;
visible differences between target and live resources;
manual or automated reconciliation;
application history tied to Git revisions;
one control plane for multiple Kubernetes clusters;
project and role boundaries for shared installations.

Argo CD does not decide whether a Git change is safe. It faithfully renders and applies the selected source. Review, testing, policy enforcement, and artifact integrity remain part of your delivery system.

The Application boundary

An Application is the main unit you operate. It groups Kubernetes resources generated from a source and managed as one deployment boundary.

Its specification connects four concerns:

Concern	Application field	Question
Source	repository URL, revision, path, or chart	What should be rendered?
Destination	cluster API address or name, plus namespace	Where should it run?
Project	`spec.project`	Which sources, destinations, and resource kinds are allowed?
Sync policy	`spec.syncPolicy`	When and how may live state change?

Argo CD supports plain YAML and JSON directories, Kustomize, Helm, Jsonnet, and configured plugins. The repository server generates manifests. The application controller compares and reconciles them. The API server exposes status and operations to the web interface, command-line client, and automation.

The source is not necessarily a raw manifest directory. A Helm chart or Kustomize tree is still rendered before comparison. For Helm, Argo CD uses Helm to generate manifests; application lifecycle management remains Argo CD's job.

Refresh, diff, and sync

A refresh updates Argo CD's comparison of target and live state. It does not apply resources.

A diff shows the result of that comparison. Read the diff before you sync when the change can delete, replace, or reconfigure resources.

A sync moves live state toward target state. A manual sync happens when an operator or automation requests it. An automated sync begins when Argo CD detects a qualifying difference and the Application enables automated sync.

Automated sync is not one switch for every corrective behavior:

automated sync can apply new desired state from Git;
pruning must be enabled before automated sync deletes resources removed from Git;
self-heal must be enabled before live-only drift triggers automated correction;
allow-empty must be enabled before automated pruning can remove every target resource.

These defaults are safety boundaries. Enable each behavior deliberately. A repository mistake becomes a cluster change quickly when automated sync, pruning, and self-heal all run without an effective review path.

Ordering a sync

Most Kubernetes resources can be applied together because controllers resolve dependencies over time. Some releases need explicit sequencing.

Argo CD provides sync phases for coarse lifecycle stages. PreSync hooks run before ordinary sync work. Sync hooks run with the application of manifests. PostSync hooks run after a successful sync when resources are healthy. SyncFail hooks run after failure.

Within a phase, sync waves order resources by an integer annotation. Lower waves run before higher waves. Use phases for lifecycle intent and waves for ordering inside that lifecycle.

Hooks and waves can coordinate jobs such as schema preparation. They do not make a non-backward-compatible migration safe. Your application and database design still need a valid deployment sequence and recovery plan.

Projects and access boundaries

An AppProject groups Applications and constrains what they may do. A project can allow or deny source repositories, destination clusters and namespaces, and Kubernetes resource kinds. It can also define project roles and sync windows.

Argo CD's RBAC controls actions through the Argo CD API. Kubernetes RBAC controls what Argo CD's service accounts can do in each cluster. You need both layers:

Argo CD RBAC answers who may view, create, update, or sync an Application;
an AppProject answers where that Application may source and deploy resources;
Kubernetes RBAC sets the final permissions available to Argo CD in the cluster.

Treat access to the Argo CD control-plane namespace as highly privileged. The official project guidance warns that the built-in default project starts permissive. Shared installations should create explicit projects and reduce default access.

ApplicationSet scales a pattern

An ApplicationSet generates Applications from a template and parameters. It does not replace the Application controller. The ApplicationSet controller creates or updates child Applications, and the Application controller reconciles those Applications.

Generators provide the parameters. A List generator uses explicit values. A Cluster generator uses clusters registered with Argo CD. A Git generator uses repository directories or files. Matrix and Merge generators combine parameter sets.

ApplicationSet fits repeated deployment shapes, such as one Application per cluster or one Application per directory. Start with a small generator and inspect the generated Applications. Template mistakes can multiply across every generated target.

Secrets and trust

Git should hold declarations, not plaintext secrets. Argo CD's official guidance recommends populating application secrets in the destination cluster instead of injecting them during manifest generation. This keeps Argo CD from needing the secret values and separates secret rotation from application sync.

Argo CD still stores credentials for repositories and managed clusters as Kubernetes Secrets in its control plane. Protect that namespace, restrict access, encrypt cluster data at rest, and scope external-cluster credentials to the permissions Argo CD needs.

Config management plugins execute during manifest generation. Treat them as privileged code. They process repositories and may gain access to credentials available to the repository server.

Where Argo CD fits

Argo CD is a strong fit when:

Kubernetes is the deployment target;
desired application state can be rendered declaratively;
Git review is a meaningful control point;
drift visibility or correction matters;
one team needs a consistent view across clusters;
platform teams need bounded self-service for application teams.

It is a weaker fit when the target is not Kubernetes, the work is primarily imperative, or the team cannot operate another control plane. It also does not replace continuous integration, image building, vulnerability scanning, policy evaluation, secret stores, progressive traffic management, or application observability.

Argo CD can trigger ordered hooks, but it is not a general workflow engine. It can report Kubernetes resource health, but that is not the same as proving business correctness. It can roll back to a Git-recorded configuration, but stateful systems may require a separate data recovery procedure.

A path to competent use

Learn the Application source, destination, project, target state, live state, sync status, and health status.
Install a pinned Argo CD release in a disposable cluster and deploy the official guestbook example manually.
Change Git, refresh, inspect the diff, sync, and observe resource health.
Test automated sync, pruning, and self-heal separately so you can see each boundary.
Create an AppProject that allows one repository, one destination namespace, and only the required resource kinds.
Generate several Applications with a List or Cluster generator, then inspect the child resources before expanding the pattern.
Add metrics, notifications, backups, high availability, upgrade rehearsal, and recovery tests before treating Argo CD as production infrastructure.