GitOps the Hard Way, with Argo CD

How a Change Travels From Git to the Cluster

Applications and Projects: The Two Core Resources

Argo CD defines its core concepts as Kubernetes Custom Resources, primarily the Application and the AppProject.

An Application defines the desired state of a deployed workload. It specifies:

• The project the Application belongs to.
• The source of the manifests: a Git repository, a Helm chart repository, or multiple sources combined. The source includes the repository URL, a path, and a target revision (branch, tag, or commit).
• The destination cluster and namespace where the resources should be deployed.
• The sync policy, either manual or automated.

An AppProject groups Applications and defines the policies that apply to every Application in the group. A project typically constrains:

• The source repositories Applications in the project are allowed to pull from.
• The destination cluster and namespace pairs Applications in the project are allowed to deploy to.
• Default policies for the Applications, such as allowed resource kinds and sync windows.

How the Repo Server Turns Git Into Manifests

The repo-server in Argo CD retrieves the contents of the Git repositories where Application manifests are stored. Rather than cloning each repository from scratch on every request, it keeps a local clone per repository and runs incremental git fetch operations against it, pulling only the objects it does not already have. This keeps network overhead low while ensuring the repo-server works against the requested revision.

Once the repository contents are available at the target revision, the repo-server generates the final Kubernetes manifests. For a plain-manifest source this means reading the YAML directly; for Helm or Kustomize it means running the templating tool to produce rendered YAML. The repo-server caches these generated manifests so repeated requests for the same input do not trigger regeneration. The cache key is derived from the inputs: 2 Applications on the same commit but with different paths or parameters produce different cache entries.

The repo-server returns the generated manifests to the application-controller. The repo-server itself never contacts a target cluster and holds no cluster credentials. The application-controller is the component that compares the generated manifests against live cluster state and applies resources to the Kubernetes API.

Manifest generation can be memory-intensive, particularly with templating tools like Helm on large or complex applications. Operators control this in two ways: the --parallelismlimit flag on the repo-server caps how many manifest generations run concurrently, and the repo-server can be scaled horizontally by increasing its replica count.

Reconciliation: Comparing Live State Against Target State

Argo CD distinguishes between two main states:

• Live State: The current state of the application's resources in the cluster.
• Target State: Also called the desired state, it is the state defined by the manifests at the target revision in the Git repository.

The application-controller is responsible for comparing these two states. It is the core of Argo CD's reconciliation process: it tracks the live state of resources through the Kubernetes API, compares it against the generated target state, and records the result as the Application's sync status.

When the live state matches the target state:

The Application is Synced