Jon Chery
9ebc9c8868
---ci--- project: atelier phase: 6 milestone: v0.3 status: complete requirements: covered: [ATELIER-60..91] partial: [] ---/ci---
131 lines
6.7 KiB
Markdown
131 lines
6.7 KiB
Markdown
# 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) |