atelier/domains/gitops-operators/first-principles.md

GitOps + Operators — First Principles

1. The Principles

P1. Git is the Source of Truth

Desired state lives in a versioned, immutable git store. The cluster is a derivative of git, never the authority. If a state exists only in the cluster and not in git, it is drift, not truth. The commit history is the audit trail and the rollback path.

P2. Declarative Over Imperative

Express the desired cluster state, not the commands to reach it. A manifest says what should exist; the reconciler makes it so. Imperative kubectl is for inspection and incident response, not for the steady state. This is the GitOps expression of domains/kubernetes/P1 Declarative Desired State and domains/infrastructure-as-code/P1 Declarative Intent.

P3. Pull, Don't Push

Agents running inside the target pull desired state from git; the target never accepts outside push credentials. No CI pipeline holds kubectl rights against the production cluster. The cluster reaches out to git, not the other way around. This is the security primitive of GitOps: the blast radius of a compromised CI is bounded by what CI can push, and a pull model gives CI nothing to push.

P4. Continuous Reconciliation

The reconciliation loop is the primitive. Drift is detected and corrected automatically, not on-demand. A manual apply is an exception, not the workflow. The loop runs continuously; the gap between "git changed" and "cluster matches git" is measured in seconds, not tickets.

P5. State is Immutable and Versioned

Every change to desired state is a commit. History is the audit trail and the rollback path. A revert is a rollback; a force-push is history deletion. The git store is treated like domains/infrastructure-as-code/P3 State is Truth — lose it or tamper with it, and you lose the ability to reason about the system.

P6. Operators Encode Domain Knowledge

Operational expertise lives as CRDs plus controllers, not as runbooks that humans must remember. An operator is a control loop that encodes how to reconcile a specific domain (a database, a message queue, a certificate). The operator is the deepest expression of domains/kubernetes/P1 Declarative Desired State — the domain knowledge is the desired state.

P7. Progressive Delivery is Reversible by Construction

Canary and blue-green are staged, metric-gated, and one-command abortable. Promotion without a rollback path is a violation. A rollout that cannot be aborted is a deploy, not a progressive delivery. This is the GitOps extension of domains/devops/P5 Progressive Delivery and domains/kubernetes/P10 Roll Forward, Roll Back.

P8. Reconcile, Don't Mutate by Hand

Manual kubectl apply or kubectl edit on a GitOps-managed resource is an incident. The reconciler will overwrite the hand edit on the next loop; the hand edit was never truth. Drift back to git is the recovery, not the failure. This is the GitOps angle on domains/infrastructure-as-code/P9 Drift is Recoverable.

P9. Failure is Observable and Surfaced

Sync failures, health degradation, and rollout-stall events emit status and notifications. Silent drift is the bug. A GitOps controller that fails to sync without surfacing the failure has violated the contract — you cannot fix what you cannot see (domains/observability/metrics.md).

P10. Least Privilege Reconciliation

The controller's credentials are scoped to the namespaces and resources it reconciles. No cluster-admin GitOps robots. One credential set per boundary; the reconciler sees only what it reconciles. This is the GitOps angle on domains/kubernetes/P7 RBAC by Intent, Not Identity and domains/security/authorization.md.

2. Core Principle Trace

Each GitOps + Operators P-rule derives from one or more core C-rules (C1–C8). The matrix extension lands in P4 of the v0.3 plan; the traces below are authoritative.

P-rule	Core	Why
P1 Git is the Source of Truth	C1, C5	Correctness of state; reversibility via history
P2 Declarative Over Imperative	C2, C3	Clarity of intent; simplicity of mental model
P3 Pull, Don't Push	C1, C4	Correctness via security; locality of credentials
P4 Continuous Reconciliation	C7, C1	Observability of drift; correctness of convergence
P5 State is Immutable and Versioned	C5	Reversibility via version history
P6 Operators Encode Domain Knowledge	C6, C2	Composability of expertise; clarity of operational intent
P7 Progressive Delivery is Reversible	C5, C1	Reversibility of promotion; correctness of abort
P8 Reconcile, Don't Mutate by Hand	C1, C7	Correctness of single source; observability of drift
P9 Failure is Observable and Surfaced	C7	Observability of reconciliation
P10 Least Privilege Reconciliation	C1, C8	Correctness via security; economy of trust

3. What Violates These Principles

Violation	Principle Breached
CI pipeline pushes manifests to the cluster	P3 Pull, Don't Push
A resource exists in the cluster but not in git	P1 Git is the Source of Truth
kubectl edit on a GitOps-managed resource	P8 Reconcile, Don't Mutate by Hand
Reconciler with cluster-admin ClusterRoleBinding	P10 Least Privilege Reconciliation
Sync failure with no status or notification	P9 Failure is Observable and Surfaced
Canary with no abort/rollback path	P7 Progressive Delivery is Reversible
Operator runbook that exists only in a wiki	P6 Operators Encode Domain Knowledge
Reconciler that applies on a cron, not continuously	P4 Continuous Reconciliation
Force-push rewrites GitOps repo history	P5 State is Immutable and Versioned
Imperative deploy script as the steady state	P2 Declarative Over Imperative

4. Relationship to Other Domains

GitOps + Operators is the deployment-automation layer above domains/kubernetes/ and domains/infrastructure-as-code/. It borrows their declarative-reconciliation model and adds the git-as-source-of-truth and pull-based credential boundaries. Cross links are one-directional (per D-026 extended):

• domains/kubernetes/P1 Declarative Desired State ← P2
• domains/kubernetes/P10 Roll Forward, Roll Back ← P7
• domains/infrastructure-as-code/P1 Declarative Intent ← P2
• domains/infrastructure-as-code/P3 State is Truth ← P1, P5
• domains/infrastructure-as-code/P9 Drift is Recoverable ← P4, P8
• domains/devops/P4 Rollback First ← P5, P7
• domains/devops/P5 Progressive Delivery ← P7
• domains/devops/P6 Configuration as Code ← P1, P2
• domains/security/secrets.md ← P3, P10 (reconciliation credentials)
• domains/security/supply-chain.md ← P5 (signed, immutable provenance)
• domains/observability/metrics.md ← P4, P9 (reconciliation + rollout metrics)