English for Flux CD Developers
Vocabulary for developers practicing GitOps with Flux CD — reconciliation loops, source controllers, kustomizations, and drift detection — for teams discussing Kubernetes delivery in English.
Flux CD is a GitOps tool for Kubernetes that continuously reconciles a cluster’s actual state with the desired state declared in a Git repository, rather than pushing changes to the cluster imperatively. The core idea — Git as the single source of truth, with automated controllers pulling changes rather than a human or CI pipeline pushing them — reshapes how teams talk about deployments. If your team runs Flux, here’s the English you’ll need for GitOps and incident discussions.
The GitOps Model
Git as the source of truth — the principle that the cluster’s desired state lives entirely in a Git repository, and any change to the cluster should happen by changing Git, not by running kubectl apply by hand.
“Don’t patch the deployment directly with kubectl — that change will just get reverted on the next reconciliation, since Git is the source of truth, not the live cluster.”
Pull-based deployment — Flux’s controllers run inside the cluster and pull changes from Git on an interval, rather than an external CI pipeline pushing changes into the cluster. “We don’t need cluster credentials in CI at all — Flux pulls from the repo itself, which is a smaller attack surface than a pipeline pushing with a cluster admin token.”
Reconciliation loop — the continuous process where a Flux controller compares the live cluster state to the desired state in Git and applies any differences it finds. “The reconciliation loop runs every minute by default — if someone manually deletes a pod, it just comes back on the next reconciliation.”
Core Controllers
Source controller
The source controller watches Git repositories, Helm repositories, or S3 buckets and makes their content available to other Flux controllers as an artifact.
“The source controller is reporting the Git repo as unreachable — check whether the deploy key expired before assuming it’s a reconciliation bug.”
Kustomize controller
The kustomize controller applies Kustomize-built manifests from a source to the cluster, and is the piece most commonly referred to as “a kustomization.”
“We split the kustomization into
baseandoverlays/production— the kustomize controller applies the overlay, which patches image tags on top of the shared base.”
Helm controller
The Helm controller manages Helm releases declaratively, reconciling a HelmRelease resource against the chart and values defined in Git.
“Instead of running
helm upgrademanually, we define aHelmReleaseobject — the Helm controller reconciles it automatically whenever the chart version in Git changes.”
Drift and Sync
Drift — any difference between the cluster’s actual live state and the state declared in Git, whether from a manual kubectl change, an autoscaler, or an external tool.
“The dashboard flagged drift on the
paymentsnamespace — someone bumped replicas manually, and Flux is about to reconcile it back down unless we update Git instead.”
Drift detection — Flux’s ability to notice when the live cluster no longer matches Git and automatically correct it (or alert, depending on configuration).
“Drift detection caught the manual scaling change within a minute — that’s exactly the safety net GitOps is supposed to provide.”
Suspend / resume reconciliation — temporarily pausing a Flux resource’s automatic reconciliation, often used during a manual debugging session.
“Suspend the kustomization before you start debugging live in the cluster — otherwise Flux will revert your manual changes mid-investigation.”
Common Mistakes
| Mistake | Correction |
|---|---|
| ”I’ll just kubectl apply this quickly” | Any direct cluster change will be reverted on the next reconciliation — change Git instead, or suspend reconciliation first. |
| Calling every YAML file “a kustomization” | A kustomization specifically refers to the Flux resource (or kustomization.yaml) the kustomize controller reconciles. |
| Assuming Flux pushes changes | Flux is pull-based — controllers inside the cluster pull from Git, nothing pushes into the cluster from outside. |
| Debugging drift without checking who caused it | Distinguish manual changes, autoscalers, and other controllers before assuming it’s a Flux misconfiguration. |
Practice Exercise
- Explain, in two sentences, why “Git is the source of truth” matters when someone suggests a quick
kubectl apply. - Write a short incident note explaining that a kustomization was suspended during a live debugging session and needs to be resumed.
- Draft a message to a teammate explaining the difference between the source controller and the kustomize controller.