Skip to content

ADR-002: Use FluxCD v2 for GitOps Continuous Delivery

Status

Accepted

Date

2026-03-07

Context

The cluster state must be managed declaratively from Git. All changes (new services, version upgrades, config changes) should be applied by committing to the repository, not by running kubectl apply manually. This ensures reproducibility, auditability, and teaches production GitOps workflows.

Decision

Use FluxCD v2 (CNCF Graduated) with: - source-controller — watches GitHub repo and Helm chart repos - kustomize-controller — reconciles Kustomize manifests - helm-controller — reconciles HelmRelease objects

Bootstrap command: 

flux bootstrap github \
  --owner=<github-username> \
  --repository=HomeKube \
  --branch=main \
  --path=clusters/local \
  --personal

Alternatives Considered

Tool Reason Not Chosen
ArgoCD Excellent UI and multi-cluster features; but heavier (requires Redis, Dex, UI server), more UI-driven which reduces CLI/K8s-native learning
Manual kubectl apply No GitOps; no audit trail; not representative of production workflows
Helm only Helm manages releases but has no continuous reconciliation loop; drift is not auto-corrected
Spinnaker Enterprise CD platform, massively over-engineered for a local sandbox

Consequences

Positive

  • Git is the single source of truth — every change is an atomic commit
  • Pull-based model: cluster pulls from Git, no inbound network access required, no cluster credentials stored in CI
  • Kubernetes-native: Flux uses CRDs (HelmRelease, Kustomization, GitRepository) — learning Flux is learning K8s patterns
  • Auto-corrects drift — if someone runs kubectl edit manually, Flux reverts it on the next reconciliation
  • CNCF Graduated — production-grade, well-documented, active community

Negative

  • CLI-first: no UI out of the box (Flux UI / Weave GitOps is available but not included in Phase 1)
  • Initial flux bootstrap requires a GitHub Personal Access Token
  • Reconciliation loop interval (default 1h) means changes are not instant — use flux reconcile to force immediate sync during development

Trade-offs

CLI discipline and Git-first workflow are prioritised over UI convenience. This reinforces best practices for production GitOps.