# 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)