Opscraft
GitOps with Flux & Argo CD · Lesson 2 of 6 · 7 min read

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
Enlarge diagramGit / OCI /Helm reposource-controllerfetches artifactskustomize-controllerapply, prune, SOPShelm-controllerHelmReleasesclusterAlso: notification-controller (alerts, webhooks) · image-reflector + image-automation (new tags → Git)
Figure 1. Flux is a set of controllers. Sources fetch artifacts; the Kustomize and Helm controllers apply them; image controllers write new tags back to Git.
Swipe sideways to see all of it, or tap to open it full screen.

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).

Enlarge diagramflux bootstraprun onceInstallcontrollersinto flux-systemCommitmanifestsinto the cluster'sfolderCreate Gitsource +Kustomizationpointing at thatpathSelf-managingupgrade Flux =commit12345
Figure 2. flux bootstrap: Flux installs itself and then commits its own manifests to Git, so from then on Flux manages Flux.
Swipe sideways to see all of it, or tap to open it full screen.

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 Certificate before cert-manager's CRDs exist fails.
  • Health checks (wait: true or healthChecks:) make a Kustomization Ready only when workloads are healthy — downstream dependsOn waits for that.
  • Server-side apply with field ownership; drift on fields Flux manages is corrected each interval. kustomize.toolkit.fluxcd.io/ssa: Ignore or IfNotPresent annotations for special cases.
  • postBuild substitution — ${cluster_name} style variables from ConfigMaps/Secrets per cluster.
  • Suspend for emergencies: flux suspend kustomization apps stops reconciliation (so a hotfix isn't reverted); flux resume afterwards. Always record why and reconcile Git afterwards.
Enlarge diagraminfra-controllerscert-manager, ESO, LBcontrollerinfra-configsClusterIssuers,StorageClassesappsorders, payments…thenthenprune: true removes what you delete from Git · wait: true means Ready only when workloads are healthy
Figure 3. dependsOn orders the layers: controllers and CRDs first, then their configs, then apps. Each waits until the one before is Ready.
Swipe sideways to see all of it, or tap to open it full screen.

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.

Enlarge diagramgit pushto mainGitHubwebhookReceivera Flux webhookreconcile nownot in 10 min
Figure 4. Faster deploys: a GitHub webhook hits a Flux Receiver, which reconciles immediately instead of waiting for the interval.
Swipe sideways to see all of it, or tap to open it full screen.

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).

Enlarge diagramKustomization team-ordersserviceAccountName: team-ordersnamespace team-ordersRole allows only this namespaceKustomization team-paymentsserviceAccountName: team-paymentsnamespace team-paymentsRole allows only this namespaceapplies asapplies as
Figure 5. Multi-tenancy: each team's Kustomization is applied as that team's service account, so its RBAC limits what Git can change.
Swipe sideways to see all of it, or tap to open it full screen.