atelier/domains/gitops-operators/flux.md

# Flux — Derived Rules

> Derives from `domains/gitops-operators/first-principles.md`.
> Applies P1–P10 to Flux specifically. For the ArgoCD-vs-Flux
> decision, see the decision matrix at the end of this doc and in
> `argocd.md`.

## What Flux Is (P1 Git is the Source of Truth, P3 Pull, Don't Push)

- Flux is a set of composable controllers — the GitOps Toolkit —
  that run inside the target cluster, pull desired state from git
  or OCI registries, and reconcile the cluster to match. CI never
  holds `kubectl` rights against the cluster (P3).
- The composable-controller architecture is a C6 (Composability)
  exemplar: each controller does one thing (source, kustomize, helm,
  notification) and the controllers compose into a full GitOps
  system.
- Flux supports Helm releases, Kustomize overlays, and raw
  manifests — see `domains/kubernetes/helm.md` and
  `domains/kubernetes/kustomize.md`.

## GitOps Toolkit Controllers (P6 Composability, P4 Continuous Reconciliation)

- **source-controller** — pulls git, Helm, OCI, and bucket sources;
  emits artifacts (tarballs) with a digest. The source is the
  pinned input to reconciliation (P5 versioning by digest).
- **kustomize-controller** — reconciles Kustomization CRDs against
  the artifacts from source-controller. Runs continuously (P4).
- **helm-controller** — reconciles HelmRelease CRDs against Helm
  charts from source-controller.
- **notification-controller** — emits events and notifications for
  sync, health, and source-readiness events (P9).
- **image-automation-controller** (optional) — updates git with new
  image tags when a policy matches, closing the "latest image"
  loop declaratively.

## Kustomization CRD (P2 Declarative Over Imperative, P4)

- A Kustomization binds "this source" to "this target namespace"
  with a reconciliation interval. The reconciler loops
  continuously; drift is corrected automatically (P4).

```yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: payments-api
  namespace: flux-system
spec:
  sourceRef:
    kind: GitRepository
    name: platform
    namespace: flux-system
  path: ./manifests/prod
  targetNamespace: payments
  interval: 1m
  prune: true
  wait: true
  healthChecks:
    - apiVersion: apps/v1
      kind: Deployment
      name: payments-api
      namespace: payments
```

- `prune: true` deletes resources removed from git. `wait: true`
  waits for health checks before declaring the Kustomization ready.
  Disable prune for workloads that need manual removal gates.

## HelmRelease CRD (P6 Composability, cross-link helm.md)

- A HelmRelease binds a Helm chart (from a HelmRepository or OCI
  source) to target values and a target namespace. helm-controller
  renders and applies it. See `domains/kubernetes/helm.md` for the
  chart model.
- Pin the chart version in the HelmRepository or the HelmRelease.
  Never float `latest` — unversioned charts drift (P5).

## OCI Sources (P5 State is Immutable and Versioned)

- source-controller can pull from OCI registries (Helm charts as
  OCI artifacts, or generic OCI repositories). The digest is the
  version — immutable by construction (P5).
- OCI sources close the supply-chain loop: the manifest is signed
  and immutable in the registry, and Flux pulls it by digest. Cross-
  link `domains/security/supply-chain.md` for signed-provenance
  principles.

## Reconciliation and Drift (P4 Continuous Reconciliation, P8)

- Flux reconciles on `interval` (default 1m) and on webhook event.
  Drift between git and cluster is detected each interval and
  corrected (with `prune` + `selfHeal` semantics).
- Hand-edited drift on a Flux-managed resource is overwritten on the
  next loop — the hand edit was never truth (P8). The recovery is
  to fix git, not to `kubectl apply`.

## Notifications and Events (P9 Failure is Observable and Surfaced)

- notification-controller emits events for source readiness, sync
  success/failure, and health transitions. Wire them to Slack,
  PagerDuty, or a webhook. Silent drift is the bug (P9).
- Events flow to `domains/observability/metrics.md` via the
  notification controller's provider model — sync and health as
  first-class signals.

## RBAC and Multi-Cluster (P10 Least Privilege Reconciliation, P4)

- Flux's controllers run with a ServiceAccount in `flux-system`.
  Scope that account to the namespaces Flux reconciles. Do not bind
  it to `cluster-admin` (P10). See `domains/kubernetes/rbac.md` and
  `domains/security/authorization.md`.
- Flux is per-cluster by design (one Flux install per cluster). For
  multi-cluster, use one repo with per-cluster paths, or a fleet
  tool that bootstraps Flux per cluster. Per-cluster autonomy is a
  feature, not a limitation — it bounds the blast radius of a
  compromised controller (P4 locality, P10).

## Secrets (P10, cross-link security/secrets)

- Do not store raw Secrets in the GitOps repo. Use the
  SOPS-compatible decryption in kustomize-controller, or External
  Secrets Operator, so the git store holds encrypted material only.
  See `domains/security/secrets.md`.

## ArgoCD vs Flux — Decision Matrix (IDEATE-21, D-039)

| Axis | ArgoCD | Flux |
|------|--------|------|
| Architecture | Monolithic controller + Application CRD | Composable GitOps Toolkit controllers (source, kustomize, helm, notification) |
| Reconciliation unit | Application (one CRD per app) | Kustomization / HelmRelease (one per deploy unit) |
| UI | Web UI + CLI (full dashboard, tree view, diff viewer) | CLI-first; UI via Weave GitOps or FluxUI (add-on) |
| Sync model | Periodic poll or webhook; sync waves + hooks | Poll + webhook; runs continuously, no explicit sync waves |
| Multi-cluster | One ArgoCD manages many clusters (hub-and-spoke) | One Flux per cluster (per-cluster autonomy) |
| Templating in repo | Helm, Kustomize, ksonnet, raw manifests, Jsonnet | Helm, Kustomize, raw manifests |
| RBAC | Built-in RBAC + SSO + AppProjects | Kubernetes RBAC (no built-in RBAC layer) |
| Progressive delivery | Argo Rollouts (sister project, tight integration) | Flagger (sister project, tight integration) |
| Best for | Teams wanting a UI, multi-cluster from one pane, App-of-Apps bootstrapping | Teams wanting composable controllers, per-cluster autonomy, minimal footprint |
| Watch out for | Monolithic controller scaling, UI as ops crutch, AppProject sprawl | No native UI, steeper learning curve, manual multi-cluster orchestration |

- Use Flux when you want composable controllers, per-cluster
  autonomy, and a minimal footprint. Use ArgoCD when you want a UI,
  central multi-cluster management, and sync-wave ordering.
- Both are CNCF graduated and both implement the OpenGitOps
  principles. The choice is architectural fit, not correctness. See
  `argocd.md` for the ArgoCD-side perspective.

## What Violates Flux Discipline

| Violation | Principle |
|-----------|-----------|
| CI pipeline with `kubectl` rights pushing to the cluster | P3 Pull, Don't Push |
| HelmRelease with no pinned chart version | P5 State is Immutable and Versioned |
| Flux ServiceAccount bound to `cluster-admin` | P10 Least Privilege Reconciliation |
| Kustomization with no `healthChecks` on a prod app | P9 Failure is Observable and Surfaced |
| No notification provider wired for sync failures | P9 Failure is Observable and Surfaced |
| Raw Secret in the GitOps repo | P10, `domains/security/secrets.md` |
| Manual `kubectl edit` on a Flux-managed resource | P8 Reconcile, Don't Mutate by Hand |
| `interval: 24h` on a prod Kustomization (drift window too wide) | P4 Continuous Reconciliation |