Argo CD architecture: rendering, reconciliation and application health
Trace an Argo CD application through the API server, repository server and application controller. Distinguish rendering, sync and health failures with an operational example.
TL;DR: Argo CD renders desired Kubernetes objects from a configured source, compares them with live objects and applies permitted changes. The repository server renders manifests; the application controller reconciles them. A synchronized application can still be unhealthy.
Three components answer different questions
An Application identifies a source revision and path, a destination cluster and namespace, and synchronization policy. The Argo CD API server serves the UI and CLI and enforces access policy. The repository server retrieves source and generates manifests, including rendering supported Helm or Kustomize inputs. The application controller compares desired and live objects and performs reconciliation operations.
These responsibilities are described in the Argo CD architecture documentation. The Kubernetes API server remains the authority for accepting cluster changes. Argo CD does not schedule Pods or replace the Deployment controller.
The diagram separates source rendering from the running workload. A repository outage may prevent new reconciliation while existing Pods continue serving. A cluster credential failure may leave manifests renderable but prevent the controller from reading or changing the destination.
Read sync and health independently
| Observation | What it establishes | Next evidence to inspect |
|---|---|---|
| Manifest generation failed | Desired objects could not be produced | Source revision, path, values and renderer error |
| OutOfSync | Desired and live objects differ under comparison rules | Diff and ownership of the differing field |
| Synced but Degraded | Desired objects match, but observed health is poor | Workload conditions, events and dependencies |
| Progressing | Resources have not completed their expected transition | Rollout status and time spent at each stage |
| Permission denied | An operation failed an authorization boundary | Argo RBAC or destination-cluster RBAC, depending on the request |
Avoid starting every investigation with a forced sync. If the desired manifest contains the wrong port, successfully applying it again reproduces the failure. If Pods cannot pull an image, changing comparison options will not fix registry access.
Follow a realistic failure
A team updates a chart value from image tag 2.1 to 2.2. Argo CD reports Synced, but the application stays Degraded. First inspect the generated Deployment and confirm that its image and configuration match the reviewed change. Then follow the Deployment to its ReplicaSet and Pods. An ImagePullBackOff condition directs the investigation toward image existence, digest, registry credentials or node connectivity.
Now change the scenario: the Application reports a manifest-generation error before any Kubernetes update occurs. Inspect the source path, chart dependencies and values. The renderer may reject invalid YAML or a template expression. The old healthy workload can remain in place because the new desired objects were never produced.
These two symptoms can appear after the same Git commit but fail at different boundaries. In an interview, name the component that owns the next piece of evidence.
Automated sync is a policy choice
Automated sync, pruning and self-healing have distinct effects. Automatic sync applies eligible desired changes. Pruning permits removal of live resources that disappear from the desired set. Self-healing allows correction of live drift back toward the configured desired state. Review all of them explicitly; enabling one does not justify assuming the others are enabled.
The automated sync guide documents these controls and the restriction on rollback while automated sync is enabled. In a GitOps workflow, restoring the desired revision in Git often provides a clearer recovery record than an unrecorded live edit. First establish compatibility with current data, especially after migrations.
A webhook can shorten the time before Argo CD notices a change. Design its delivery and duplicate handling around the sender's actual contract. It is an event notification alongside reconciliation, rather than a reason to give the CI build job broad cluster credentials. Argo CD itself still holds privileged access appropriate to its destinations. Protect that controller and restrict what each application project may deploy.
Ownership prevents controllers from fighting
An autoscaler may legitimately change a Deployment's replica count. If another reconciler insists on a fixed replica count, the two can repeatedly overwrite each other. Decide who owns the field and configure the comparison and synchronization behavior deliberately. An ignore rule that hides an important security field can also hide unwanted drift.
With Helm as the source, distinguish rendering a chart from having Helm own an imperative release lifecycle. Inspect the controller's documented behavior for hooks and values. See Helm release lifecycle before assuming helm rollback and an Argo CD reconciliation operate on the same release history.
Diagnose before changing policy
Self-check: an operator scales a Deployment from four Pods to six during an incident. Minutes later it returns to four. What should you establish?
Check the desired manifest, Argo CD self-heal behavior, autoscaler ownership and audit events. If Git still declares four and reconciliation owns that field, the return is expected. Record an appropriate desired-state change or a controlled temporary override with an owner and expiry. Blindly turning off reconciliation for every application expands the incident's scope.
Practice Argo CD self-healing and sync waves, using the general reconciliation model to explain why the correction repeats.
For release dependency ordering, Argo CD sync waves and hooks works through a migration whose negative wave cannot move its Secret ahead of the PreSync phase.