The flux CLI

The command families that actually get used in production: reconcile, suspend, resume, trace, diff, build, check, logs, events, tree, stats, and the export-then-commit workflow that keeps the CLI GitOps-correct.

Overview

What the flux CLI is

The flux CLI is the operational surface of Flux v2: a single Go binary with no daemon, no local state and no privileged access beyond your kubeconfig. Every subcommand resolves to one of four operations against the Kubernetes API.

> [!WARNING] Engineers who have only read the quickstart tend to believe flux reconcile deploys code. It does not; interviewers probe this.

Reconcile versus interval

Every Flux object has spec.interval, the drift-correction cadence (minimum 60 seconds on a Kustomization). Each window, the controller re-fetches the source, rebuilds and re-applies, correcting out-of-band changes.

Consumer spec.interval — How fast you heal from drift
Source revision change event — How fast a merge reaches production
flux reconcile — Not waiting for either; sets reconcile.fluxcd.io/requestedAt and blocks until Ready

Suspend versus delete

During an incident you often need Flux to stop reverting a manual fix.

Delete the Kustomization — Garbage-collects everything it owns if prune is enabled
flux suspend — Sets spec.suspend: true; reconciliation stops and managed resources stay exactly where they are

Suspend is also the planned-maintenance mechanism: suspend before a manual database migration, resume after.

> [!TIP] Suspension is not recursive the way people expect. Suspend the object that actually owns the resource you are editing.

Forensics: trace and tree

flux trace — Upward — Which Git commit put this object here; last status at every hop
flux tree — Downward — Everything a Kustomization owns, including nested overlays

Pre-merge review: build and diff

flux build kustomization — Renders the local directory as kustomize-controller would, including postBuild substitution and targetNamespace
flux diff kustomization — Same build, then a server-side dry-run apply; prints the delta and exits 1 when differences exist

> [!IMPORTANT] The exit code makes flux diff a CI gate. With --strict-substitute it catches undeclared postBuild variables, which plain kustomize build renders as empty strings.

The workflow question

flux create source git and flux create kustomization apply objects directly to the cluster. In GitOps that is an anti-pattern: the cluster now holds state Git does not know about.

> [!TIP] Every flux create command accepts --export. Export, commit, push and let the root Kustomization apply it: that is the operation an interviewer is listening for.

Key concepts

reconcile.fluxcd.io/requestedAt: The annotation flux reconcile writes onto a Flux object with the current timestamp. Changing its value is what tells the controller to reconcile now rather than at the next spec.interval. The controller records the value it handled in status.lastHandledReconcileAt, which is how the CLI knows the request was picked up.
flux reconcile --with-source: Reconciles the referenced source object first, then the consumer. Without it, kustomize-controller or helm-controller re-applies whatever artifact source-controller already holds, which may predate the commit you just pushed. This flag is why "I reconciled and nothing changed" is usually a missing --with-source.
flux suspend and flux resume: Toggle spec.suspend on a Flux object. Suspended objects stop reconciling entirely, so manual kubectl changes to the resources they manage survive. Nothing is deleted. On resume, the controller reconciles and reverts any manual change that is not in the source.
flux trace: Reverse-resolves any Kubernetes object to the Flux objects that manage it, printing the Kustomization or HelmRelease, the source kind and name, the revision, and the last reconciliation status at each hop. Accepts --kind and --api-version to disambiguate custom resources.
flux build kustomization: Fetches the in-cluster Kustomization spec, applies its transformations to a local path, and prints multi-doc YAML on stdout. Reproduces exactly what kustomize-controller would apply, including postBuild substitution. --dry-run skips substitutions that come from Secrets and ConfigMaps.
flux diff kustomization: Builds as above, runs a server-side dry-run apply, and prints the differences. Exit code 0 means no differences, 1 means differences found, greater than 1 means an error occurred. Designed to be a CI gate, not just a human-readable report.
--export: A flag on every flux create subcommand that prints the generated custom resource to stdout instead of applying it to the cluster. The bridge between the convenience of the CLI and the discipline of GitOps: generate, commit, let the controller apply.
flux check versus flux check --pre: flux check --pre validates only the local environment and Kubernetes server version before installation. flux check validates that the installed controllers (source, kustomize, helm, notification by default) are deployed and healthy and reports their versions. --components-extra adds image-reflector and image-automation to the check list.

When to use it

Immediately after merging a change, when waiting for the next interval is unacceptable: flux reconcile kustomization --with-source
During an incident when a manual fix must survive: flux suspend kustomization , fix, then flux resume once the permanent change is merged
Answering an audit or postmortem question about provenance: flux trace / -n to get the owning Kustomization, source, and Git commit
As a pull request gate in CI: flux diff kustomization --path --strict-substitute, using the exit code as pass or fail
Adding any new Flux object to a cluster: flux create ... --export redirected into the repository, never bare flux create
First triage of a broken cluster: flux check, then flux get all -A --status-selector ready=false, then flux events and flux logs

Interview questions

What exactly does flux reconcile do, and how does it relate to spec.interval?
A Deployment appeared in production that nobody recognizes. How do you find out what put it there?
How do you review a Flux manifest change before it merges, and why is plain kustomize build not enough?
Production is down and you need to make a manual change. Walk through it with Flux in the loop.
Why is flux create considered an anti-pattern in a GitOps setup, and what is the correct workflow?
flux get shows a Kustomization as not ready. Walk through your CLI debugging sequence.