Argo CD / Desired state and evidence foundations / Lesson 1

GitOps reconciliation and the Argo CD boundary

Separate desired-state generation, comparison, synchronization, resource health, and user outcomes.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Explain the repository server and application controller roles.
Distinguish a desired-state commit from an observed healthy deployment.

Desired state is an input to a control loop

Argo CD follows a declarative model in which an Application identifies desired Kubernetes configuration and a destination. The source can be rendered from supported configuration tools rather than being literal final manifests in every case. Parcel is a synthetic label service whose configuration repository describes intended resources. A reviewed commit changes desired input; it does not prove that a cluster accepted it or users received the new behavior. Keep source review, generated manifests, sync action, observed state, and business verification as distinct evidence boundaries.

Know which component answers the question

The repository server obtains and generates manifests under the configured source contract. The application controller compares desired and live state and coordinates reconciliation and sync behavior. The API server exposes management interfaces and authorization-related functions under the installation’s design. These roles help locate errors: manifest generation failure is different from a forbidden Kubernetes operation or an unhealthy workload after apply. This course uses Argo CD release-3.1 documentation as a stated learning baseline, not a claim about the newest release, installed version, or universal deployment architecture.

Comparison does not automatically mean mutation

Argo CD can report differences without applying them when the configured policy or decision requires a separate sync. Automated sync, pruning, and self-healing are distinct choices developed later. The diagram below shows conceptual evidence flow and no commands. A live object may also be changed by an operator, admission controller, or another controller, so a difference is an observation requiring ownership analysis. A manual edit can be overwritten under reconciliation policy; it is not automatically a durable correction to the declared source.

text A reconciliation evidence map

source revision -> rendered desired resources
desired resources + observed live resources -> comparison
configured decision -> sync operation -> observed resource health

The arrows describe conceptual dependencies. No repository, manifest renderer, controller, cluster, sync operation, or health endpoint is contacted or started.

Model comparison without a cluster

The complete local program below compares declared desired and observed replica values. It reports drift for one synthetic resource. It does not implement Kubernetes defaulting, Argo CD normalization, ownership, ignored differences, health assessment, or sync. Those mechanisms make real comparison richer than dictionary equality. Its narrow purpose is to show that observing a mismatch is separate from choosing or performing a correction. The desired record is teaching input, not a signed or authorized source of truth.

python A local synthetic drift observation

desired = {"parcel": {"replicas": 2}}
observed = {"parcel": {"replicas": 1}}
drift = sorted(name for name in desired if desired[name] != observed.get(name))
print(drift)
print("comparison only; no correction performed")

Expected output

['parcel']
comparison only; no correction performed

Only in-memory dictionaries are compared. No Argo CD or Kubernetes behavior is emulated, and no resource is changed.

A green controller view has a bounded meaning

Sync status describes the comparison contract, while health evaluates resource-specific observations. Neither universally proves that a user can purchase a correct label or that external carrier integration works. Define a bounded user verification path separately. Record source and rendered inputs, destination identity, operation result, and observed resource identity when reviewing adoption. If a dashboard looks healthy but users fail, investigate the uncovered contract rather than declaring that GitOps is broken. An honest control-loop model makes automation useful without extending its evidence beyond what it actually measures.

Common errors and fixes

A merged desired-state commit is reported as completed adoption.

Why it happens: Source approval was confused with target-side observation.
How to fix it: Verify generation, sync outcome, observed identity, and relevant user behavior separately.
Prevent it next time: Name each evidence boundary in release records.

Every OutOfSync observation is treated as an instruction to apply immediately.

Why it happens: Comparison was confused with authorization and mutation policy.
How to fix it: Review ownership, intended source, and the configured sync decision.
Prevent it next time: Keep reporting and correction authority separate.

Healthy resource status is described as proof of every business journey.

Why it happens: Resource-specific checks were stretched beyond their scope.
How to fix it: Define and verify the relevant user outcome independently.
Prevent it next time: Document health assumptions and known exclusions.

Check your understanding

1. Parcel’s desired replicas are two and the observed value is one. Does the local model increase capacity?

Show worked solution

No. It reports a mismatch and performs no correction. Real Argo CD behavior depends on the Application policy, permissions, object ownership, and cluster state. A comparison result is evidence for a decision rather than authority to mutate.

2. Why might an application be synchronized while a customer journey still fails?