Desired state, drift and reconcile
Understand state snapshots, classify drift and admit reconciliation without creating an unsafe loop.
Three separate views
| View | Meaning | Does it mutate? |
|---|---|---|
| Desired state | Latest persisted target snapshot | No |
| Observed state | Latest persisted discovery/health snapshot | No |
| Drift | Computed differences between identified snapshots | No |
| Reconcile | Guarded OperationRun that attempts an approved convergence | Yes |
Safe reconciliation workflow
- 01
Refresh evidence
Confirm the observed snapshot is current and belongs to the intended cluster.
- 02
Classify differences
Separate expected external change, stale observation, unsupported field and actionable drift.
- 03
Dry-run guardrails
Review maintenance window, scope, impact, agent/provider readiness and confirmation.
- 04
Admit one reconcile
Use one idempotency key and follow the returned OperationRun. Do not poll by resubmitting.
- 05
Accept new state
Verify desired, observed and drift views converge with retained evidence.
API map
Command
GET /api/v1/clusters/{clusterId}/desired-state
GET /api/v1/clusters/{clusterId}/observed-state
GET /api/v1/clusters/{clusterId}/drift
POST /api/v1/guardrails/evaluate
POST /api/v1/clusters/{clusterId}/reconcile