GitOps reconciliation: desired state and drift

Last updated: 5 Oct 20266 min read

tutorial

GitOps uses a versioned desired state as the reviewed input to a reconciliation controller. The controller observes the live system and applies differences according to its configured policy. This is different from a CI job that directly mutates a cluster after building an image; the cluster-side controller can work without granting the CI runner broad cluster access.

Operational decision

A case-review service updates an image digest in a deployment repository through a pull request. After review, the controller notices the new commit and synchronizes the cluster. Decide separately whether automatic sync, self-heal, and pruning are enabled. Self-heal can reverse a manual emergency edit, while pruning can delete a resource removed from the repository. During an incident, operators need a documented way to pause reconciliation or commit a safe rollback; a one-off kubectl edit may be overwritten. The small manifest shows the desired image identity, not a full controller setup. Record the repository revision and the observed cluster revision so drift has an owner and a timestamp.

apiVersion: apps/v1
kind: Deployment
metadata: {name: case-review}
spec:
  replicas: 3
  selector: {matchLabels: {app: case-review}}
  template:
    metadata: {labels: {app: case-review}}
    spec:
      containers:
        - name: api
          image: registry.internal/case-review@sha256:9a09c4f113a2

Cost and verification

Reconciliation uses API calls and controller resources, but its larger cost is operational: a mistaken desired state can be applied repeatedly. Review deletion and namespace scope before enabling pruning. The sample digest is shortened and must be replaced with a real full digest. The manifest also omits resource requests, health probes, and security settings for focus; use the linked deployment lessons before running it. A synchronized controller does not prove the application is serving correct responses.