GitOps and delivery

Flux CD v2

1.What is Flux ?

Flux watches a Git repo (or OCI image or bucket) and keeps the cluster matching it, forever, by itself.

You push to Git, Flux applies it. No kubectl apply from laptops.

  • CNCF Graduated (Nov 2022)
  • Latest : Flux v2.9.6
  • Helm, Kustomize and plain YAML all work
  • Runs in the flux-system Namespace
vs kubectl applykubectl is a one-time push from your laptop. Flux is a loop that never stops and fixes drift.

Sources say where (Git, OCI, Helm). Appliers say what (Kustomization, HelmRelease).

Developer git push Git repo cluster (flux-system) poll source-controller kustomize-ctrl helm-ctrl Kubernetes API Pods / Deployments / Services
DirectionArrows run from inside the cluster outward. Nothing pushes in.

2.Why GitOps ?

GitOps = Git is the single source of truth, declarative, pulled automatically, continuously reconciled.

  • Pull model : CI needs no cluster credentials
  • Drift : live edits get reverted by Flux
  • Rollback : just git revert
  • Many clusters : one repo, different paths
Key Points
  • Reconcile runs every spec.interval
  • Also runs on a webhook (Receiver)
  • prune: true : delete in Git, deleted in cluster
  • Per-Kustomization serviceAccountName limits a team
  • kubectl get fluxcd -A shows all
  • Flagger, a sister project, adds canary and blue/green

3.The Controllers (Toolkit)

Small controllers, each owns its CRDs. Composable like Lego.

flux-system Namespace
source-controllerFetches Git, OCI, Helm repo, Bucket. Serves tarballs.
kustomize-controllerBuilds and applies with server-side apply, prune, health checks, SOPS.
helm-controllerHelm install, upgrade, rollback, uninstall from HelmRelease.
notification-controllerEvents out (Slack, Git status). Webhooks in.
image-reflectorScans registries for tags. Picks the latest by rule.
image-automationCommits new image tags back to Git.

Dashed ones are optional.

Each one owns its own CRDs and talks only through the API.
In short : Flux pulls from Git, builds with small controllers, applies, and keeps fixing drift every interval.

1.The Reconcile Loop

Drift gets undone at the next loop. A failure keeps the last good state and retries.

  1. Fetch source
  2. Build (kustomize / helm template)
  3. Diff vs live (dry-run SSA)
  4. Apply, only if drift or new revision
  5. Health check, set status Ready
  6. Wait interval, loop
Fetch Build Diff drift ? Apply Health Ready wait interval,then again

2.Getting Started

  1. flux bootstrap installs controllers in flux-system
  2. Define a source (GitRepository, OCIRepository, HelmRepository)
  3. Define what to apply (Kustomization or HelmRelease)
  4. Push to Git
  5. Flux fetches, applies, runs health checks
  6. Drift and deletions fixed at next interval
  7. notification-controller tells Slack or Git
Tip & Check
  • Use flux create source git ... --export to make YAML you commit.
  • After bootstrap, flux check should show every controller Ready. flux get all -A lists the rest.
flux CLI Git repo push install controllers in flux-system pull
GitRepository + Kustomization
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata: {name: app, namespace: flux-system}
spec:
  interval: 1m
  url: https://github.com/example/app
  ref: {branch: main}
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata: {name: app, namespace: flux-system}
spec:
  interval: 10m
  path: ./deploy
  prune: true
  wait: true
  timeout: 3m
  sourceRef: {kind: GitRepository, name: app}

3.CRD Cheat Sheet

KindapiVersionControllerWhat it does
GitRepositorysource.toolkit.fluxcd.io/v1sourceGit branch, tag, semver or commit
OCIRepositorysource.toolkit.fluxcd.io/v1sourceOCI artifact as source
HelmRepositorysource.toolkit.fluxcd.io/v1sourceHelm chart index (http or oci)
Bucketsource.toolkit.fluxcd.io/v1sourceS3-compatible bucket
Kustomizationkustomize.toolkit.fluxcd.io/v1kustomizeApply a path from a source
HelmReleasehelm.toolkit.fluxcd.io/v2helmDeclares a Helm release
Provider / Alertnotification.toolkit.fluxcd.io/v1notificationWhere and which events to send
ImagePolicyimage.toolkit.fluxcd.io/v1image-reflectorChoose latest tag

Check versions with kubectl api-resources | grep toolkit

In short : Each interval Flux fetches, builds, diffs and applies; sources say where, Kustomization and HelmRelease say what.

1.Image Automation

Flux can write new image tags back to Git. Then the normal pull flow deploys them.

NoteOptional controllers. Add them with:
flux bootstrap ... --components-extra
Image Automation Loop Registry ImageRepository ImagePolicy scan picks 5.1.x ImageUpdateAutomation commit Git repo normal pull flow deploys it GitRepository / Kustomization Registry scan ImageRepository ImagePolicy picks 5.1.x ImageUpdateAutomation commit Git repo normal pull flow GitRepository / Kustomization

2.flux Commands

CommandDescriptionExample
flux check --preCheck the cluster meets requirements (K8s v1.34.1+)flux check
flux bootstrap githubInstall controllers, commit to Git, self-manageflux bootstrap github --owner=loren --repo=fleet --path=clusters/prod
flux get all -AStatus of every Flux objectflux get kustomizations
flux reconcile kustomization <name>Sync nowflux reconcile kustomization flux-system --with-source
flux logs --level=error -AController logsflux logs -f --kind=Kustomization --name=apps
flux trace deployment/<name>Who owns this objectflux trace deployment/podinfo -n default
flux suspend / resume kustomizationPause for a live hotfixflux suspend kustomization apps
flux diff kustomization <name>Preview changes vs liveflux diff kustomization apps --path=./apps

3.Flux vs Argo CD vs CI Push

TopicFluxArgo CDCI
ModelPullPullPush
UIOperatorBuilt inNone
Drift fixAutoIf selfHealNo
Creds in CINoNoYes
ConfigCRDsApplicationScripts
Gotchas
  • Two things named Kustomization (Flux vs kustomize.config.k8s.io)
  • v1beta2 / v2beta2 removed in v2.8, run flux migrate
  • Hotfix ? flux suspend first, or the next loop reverts it
  • prune: true deletes what you drop from Git
  • Encrypt secrets (SOPS or External Secrets)
  • dependsOn needs wait to really wait
  • Interval minimum is 60 seconds
  • Stuck Ready=False ? Read the message
  • Repo layout, health, drift, multi-tenancy : Flux deep dive
In short : Image automation commits new tags to Git, the flux CLI checks, syncs, traces and pauses, and Flux is the pull-only, CRD-only cousin of Argo CD.

1.Flux Operator in brief

  • An operator from ControlPlane that installs and upgrades Flux from one FluxInstance named flux, instead of flux bootstrap.
  • distribution.version: "2.9.x" floats patches only. Pin the minor on purpose.
  • A FluxReport holds the observed state. AGPL-3.0, pre-GA (0.x). More : Flux deep dive.

2.The Flux Web UI

In the operator since v0.37.0, on by default, plain HTTP on port 9080 (Service flux-operator, leader pod only).

  • ShowsFlux objects, workloads, logs, events, graph, history
  • DoesReconcile, suspend, resume, download, restart, run job, delete pod
  • NeverEdits manifests : Git is the way in

3.Login modes and roles

ModeRuns asActions
NoneOperator SA (cluster-admin)Off
AnonymousOne shared identityBy RBAC
OAuth2 (OIDC)Each user, via CELBy RBAC
  • flux-web-userget, list, watch on */* : Secrets too
  • flux-web-adminSame, plus reconcile, suspend, resume, download, restart
Both roles read SecretsViewers mask them, but with login on the HelmRelease view shows valuesFrom Secrets in clear. RBAC has no "except" : list core minus secrets plus every other group, and keep get on ResourceSets.

4.How a request is authorized

Browser Gateway TLS, HTTPRoute Web UI operator :9080 HTTPS HTTP 1. 303 to the IdP IdP login code + PKCE 2. code to /oauth2/callback 3. CEL on claims to username, groups 4. as the operator SA + Impersonate-User, -Group API server authn the SA may impersonate ? RBAC as user allow : data deny : 403 5. RBAC decides every read and every button
  1. No session : 401, then /oauth2/authorize answers 303, Location on the IdP (code + PKCE).
  2. Code to /oauth2/callback, ID token verified.
  3. CEL validations pass; claims become user and groups (both empty : refused).
  4. Calls go as the operator SA, with impersonation.
  5. RBAC answers for the user. Buttons first run a SelfSubjectAccessReview. Impersonated also needs get + patch, FineGrained (v0.51.0) only the verb.

A removed group keeps access until the ID token expires. Keycloak : Full group path off, so groups read team, not /team, as in RBAC. See OIDC auth; Argo CD has its own policy.

5.Exposing it safely

  • No auth : port-forward only. Else its own host : HTTPRoute to flux-operator:9080, TLS at the Gateway.
  • FluxInstance cluster.networkPolicy: true (default) admits only flux-system pods. install.yaml has no web policy, so admit the proxy pods to 9080 (NetworkPolicy). The chart's policy admits all namespaces.
  • Config holds clientSecret : a SOPS Secret, hot-reloaded.
Seen in practicePitfall : narrowed roles drift : upgrades re-add the wildcard read, new CRD groups go missing. Do better : a scheduled SubjectAccessReview check that readers list every group, but no Secrets.

6.Commands

CommandDoes
kubectl -n flux-system port-forward svc/flux-operator 9080:9080Open the UI on localhost:9080, nothing exposed
flux-operator create secret web-config ui --base-url=... --issuer-url=... --client-id=... --client-secret-stdin --exportConfig Secret as YAML (OIDC by default). Encrypt it
kubectl auth can-i list secrets --as=jane --as-group=viewersWhat a UI user may do (should be no)
In short : The Web UI lives in Flux Operator on port 9080. Turn on OIDC, let impersonation hand every click to RBAC, and narrow the stock roles : both read Secrets.