Flux in depth
Architecture: the GitOps Toolkit
Flux v2 is a set of controllers and CRDs:
| Controller | CRDs | Job |
|---|---|---|
| source-controller | GitRepository, OCIRepository, HelmRepository, HelmChart, Bucket |
Fetches sources and produces versioned artifacts |
| kustomize-controller | Kustomization |
Builds and applies manifests from a source path; pruning, health checks, SOPS decryption, dependsOn |
| helm-controller | HelmRelease |
Installs/upgrades Helm charts with remediation |
| notification-controller | Provider, Alert, Receiver |
Sends events to Slack/Teams/etc.; receives webhooks to trigger reconciles |
| image-reflector-controller | ImageRepository, ImagePolicy |
Scans registries for new tags |
| image-automation-controller | ImageUpdateAutomation |
Commits updated tags back to Git |
Bootstrap
flux check --pre
flux bootstrap github \
--owner=acme --repository=platform-gitops \
--branch=main --path=clusters/prod-ap-south-1 \
--personal=false
Bootstrap installs Flux into flux-system, commits its own manifests into the repo at that path, and creates a GitRepository + Kustomization pointing at it — so Flux manages itself from Git. Upgrading Flux = changing those manifests (or re-running bootstrap).
Sources
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata: { name: platform-gitops, namespace: flux-system }
spec:
interval: 1m
url: ssh://[email protected]/acme/platform-gitops
ref: { branch: main }
secretRef: { name: flux-system } # deploy key
ignore: |
/*
!/clusters
!/apps
!/infrastructure
OCIRepository lets you publish manifests as OCI artifacts (flux push artifact) — CI pushes a signed artifact, clusters pull from ECR; useful when clusters shouldn't reach GitHub.
Kustomizations: apply, prune, health, order
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata: { name: apps, namespace: flux-system }
spec:
interval: 10m # full reconcile/drift correction period
retryInterval: 2m
timeout: 5m
path: ./apps/prod
prune: true # delete objects removed from Git
wait: true # wait for all applied resources to be ready
sourceRef: { kind: GitRepository, name: platform-gitops }
dependsOn:
- name: infra-configs # e.g. ClusterIssuers, StorageClasses
- prune uses inventory tracking: objects Flux applied and that disappear from Git are deleted. Protect objects with the annotation
kustomize.toolkit.fluxcd.io/prune: disabled. - dependsOn orders layers: CRDs/controllers → their configs → apps. Without it, applying a
Certificatebefore cert-manager's CRDs exist fails. - Health checks (
wait: trueorhealthChecks:) make a KustomizationReadyonly when workloads are healthy — downstreamdependsOnwaits for that. - Server-side apply with field ownership; drift on fields Flux manages is corrected each interval.
kustomize.toolkit.fluxcd.io/ssa: IgnoreorIfNotPresentannotations for special cases. - postBuild substitution —
${cluster_name}style variables from ConfigMaps/Secrets per cluster. - Suspend for emergencies:
flux suspend kustomization appsstops reconciliation (so a hotfix isn't reverted);flux resumeafterwards. Always record why and reconcile Git afterwards.
Operating Flux
flux get all -A
flux get kustomizations --watch
flux reconcile kustomization apps --with-source # force now
flux logs --kind=Kustomization --name=apps
flux events -n flux-system
flux tree kustomization apps # what it manages
flux diff kustomization apps --path ./apps/prod # local diff vs cluster
flux trace deployment orders -n orders # which Flux object manages this
Notifications:
apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Alert
metadata: { name: prod-alerts, namespace: flux-system }
spec:
providerRef: { name: slack-platform }
eventSeverity: error
eventSources:
- { kind: Kustomization, name: "*" }
- { kind: HelmRelease, name: "*" }
A Receiver exposes a webhook so GitHub pushes trigger an immediate reconcile instead of waiting for the interval.
Multi-tenancy in Flux
Platform team owns cluster-level config; app teams get namespaces. Flux Kustomizations can run as a tenant service account (spec.serviceAccountName) so a team's manifests are applied with only that team's RBAC — they can't create ClusterRoles or touch other namespaces. Enforce with --no-cross-namespace-refs and default service account flags on the controllers, plus policies (Kyverno/Gatekeeper).