What is GitOps reconciliation, and how do Argo CD and Flux implement it?
GitOps reconciliation rests on one loop. A controller running inside the cluster pulls the desired state from Git, compares it with the live objects in the API server, and applies changes until the two match. Git is the source of truth, and the cluster is continuously corrected toward it. CI never needs cluster credentials, because the cluster pulls changes instead of having them pushed in.
For backend services, this model brings three practical benefits:
- Auditability. Every change to a Deployment, ConfigMap or HPA is a commit with an author and a review trail.
- Rollback through Git. Reverting a commit restores the previous manifests, and the controller applies them.
- Drift correction. A manual
kubectl editmade during an incident gets detected, and optionally reverted, rather than lingering silently.
Argo CD and Flux are both CNCF graduated projects. The decision between them is about operating model, not maturity.
Architecture contrast
Argo CD centers on the Application CRD, which pairs a Git source with a destination cluster and namespace. It has three main components:
- The repo server renders manifests.
- The application controller diffs and syncs them.
- The API server backs the web UI and CLI, and enforces SSO and RBAC.
The result is a single product with a visual control plane.
Flux is a set of independent controllers, each owning one concern:
- The source controller fetches artifacts through
GitRepositoryand related CRDs. - The kustomize controller applies
Kustomizationobjects. - The helm controller reconciles
HelmReleaseobjects. - The notification controller handles alerts and incoming webhooks.
Optional image reflector and automation controllers add image updates. Flux has no built-in UI. You operate it through CRDs and the CLI, which makes it feel closer to a Kubernetes toolkit than a standalone application.
+----------------------------------+
| Git repository: desired state |
+----------------------------------+
| pull | pull
v v
+------------------------------------+ +------------------------------------+
| ARGO CD (Application CRD) | | FLUX (+ optional image automation) |
| +--------------------------------+ | | +--------------------------------+ |
| | API server: web UI, CLI, | | | | notification controller: | |
| | SSO, RBAC | | | | alerts, incoming webhooks | |
| +--------------------------------+ | | +--------------------------------+ |
| | | +--------------------------------+ |
| +------------+ +---------------+ | | | source controller | |
| | repo server|-->| application | | | | GitRepository -> artifact | |
| | (render) | | controller | | | +-------+----------------+-------+ |
| +------------+ | (diff, sync) | | | v v |
| +-------+-------+ | | +---------------+ +--------------+ |
| | | | | kustomize | | helm | |
| | | | | controller | | controller | |
| | | | | Kustomization | | HelmRelease | |
| | | | +-------+-------+ +-------+------+ |
| | | | | | |
+--------------------------+---------+ +---------+-----------------+--------+
| sync | apply | apply
v v v
+---------------------------------------------------------------------+
| Kubernetes API server: live state (drift detected, corrected) |
+---------------------------------------------------------------------+
Both tools pull desired state from Git and reconcile it against the live cluster. Argo CD does this through one product built around the Application CRD, while Flux splits the work across independent controllers driven by GitRepository, Kustomization and HelmRelease objects.
How do sync strategies differ between Argo CD and Flux?
Argo CD treats sync as an explicit operation. By default, an Application only reports drift, and someone clicks Sync or runs the CLI. With syncPolicy.automated enabled, it syncs when Git changes. prune deletes resources that were removed from Git, and selfHeal reverts changes made directly in the cluster. Ordering inside a sync comes from argocd.argoproj.io/sync-wave annotations and from PreSync, Sync, PostSync and SyncFail hooks.
Flux has no separate sync step. A Kustomization re-applies its path on every interval, so drift correction is always on. prune: true garbage-collects removed objects. dependsOn orders Kustomizations against each other, wait and healthChecks gate readiness, and flux suspend pauses reconciliation.
| Concern | Argo CD | Flux |
|---|---|---|
| Trigger | Manual, or automated on Git change | Periodic interval, plus optional webhook receivers |
| Drift reversion | Opt-in selfHeal |
Every reconcile |
| Ordering | Sync waves and hooks within one app | dependsOn between Kustomizations |
| Pause | Disable automated sync | suspend / resume |
Risks
Prune is the most dangerous default. A bad commit or a renamed path can look like "delete everything," and both tools will act on it. Self-heal undoes kubectl hotfixes made during an incident, so you should suspend reconciliation before patching. Self-heal also fights HPAs and mutating webhooks over fields such as replicas. Use ignoreDifferences in Argo CD, or rely on server-side apply field ownership in Flux, and leave those fields out of your manifests.
Ordering a schema migration Job ahead of a Deployment only sequences the apply. The Deployment waits for the migration to complete only if the tool actually evaluates that Job's health. That means hook or wave health in Argo CD, or wait/healthChecks in Flux.
# Argo CD: auto-sync on Git change, prune removed objects, revert drift
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: orders-api
namespace: argocd
spec:
project: default
source:
repoURL: git@git.example.com:platform/deploy.git
targetRevision: main
path: apps/orders-api
destination:
server:
namespace: orders
syncPolicy:
automated:
prune: true # deletes anything no longer in this path
selfHeal: true # reverts kubectl edits, including incident hotfixes
ignoreDifferences: # the HPA owns replicas, so don't fight it
- group: apps
kind: Deployment
jsonPointers:
- /spec/replicas
---
# Flux: re-apply every 5m, only after migrations Kustomization is Ready
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: orders-api
namespace: flux-system
spec:
interval: 5m
path: ./apps/orders-api
prune: true # garbage-collects objects removed from Git
wait: true # Ready only when applied objects pass health checks
dependsOn:
- name: orders-db-migrations # needs wait/healthChecks on the Job to mean anything
sourceRef:
kind: GitRepository
name: deploy
An Argo CD Application with automated sync, prune, selfHeal and an ignoreDifferences rule for HPA-managed replicas, next to a Flux Kustomization that reconciles every 5 minutes with prune, wait and dependsOn on a migrations Kustomization.
How does Helm chart handling differ in Argo CD vs Flux?
Argo CD treats a Helm chart as a template source. It renders the chart to plain manifests, roughly what helm template produces, and then applies and diffs those manifests like any other resources. No Helm release is created in the cluster, so helm list shows nothing and helm rollback has no history to work with. To roll back, you sync to an earlier Git revision or use Argo CD's own history.
Rendering without a release causes three kinds of breakage:
lookuphas no live cluster to query during rendering. It returns empty, so charts that use it to keep generated passwords or detect existing objects behave as if every render were a fresh install.- Release state such as
.Release.IsUpgradedoes not reflect reality. Templates that branch on install versus upgrade can take the wrong branch. - Hooks are mapped to Argo CD's sync phases. Common install and upgrade hooks map cleanly, but rollback and delete hooks have no equivalent, and hook ordering follows Argo CD's rules rather than Helm's.
Flux's helm-controller performs real Helm installs and upgrades. Release history, hooks, lookup and helm rollback all work as Helm intends. The trade-off is that a failed release can stall reconciliation until it is remediated. In the HelmRelease example, install.remediation.retries and upgrade.remediation.retries set how many attempts are made. upgrade.remediation.strategy chooses whether a failure triggers a rollback or an uninstall. Set these deliberately, because the defaults may leave a failed release sitting until someone intervenes.
To decide which model you need, search your charts for lookup, .Release.IsUpgrade/.Release.IsInstall, rollback or delete hooks, and runbooks that call helm rollback. If none of these appear, rendered manifests are likely sufficient.
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
name: orders-api
namespace: backend
spec:
interval: 10m # how often helm-controller reconciles the release
timeout: 5m # how long Helm waits for resources before marking failure
chart:
spec:
chart: orders-api
version: "1.4.x" # semver range resolved from the source
sourceRef:
kind: HelmRepository
name: internal-charts
namespace: flux-system
install:
remediation:
retries: 3 # retry a failed first install up to 3 times
upgrade:
cleanupOnFail: true # delete new resources created by a failed upgrade
remediation:
retries: 3 # retry a failed upgrade up to 3 times
strategy: rollback # on failure, roll back to the last good release (alternative: uninstall)
remediateLastFailure: true # also remediate after the final retry instead of leaving it failed
rollback:
cleanupOnFail: true # clean up resources left behind during the rollback
values:
replicaCount: 3
image:
tag: "2.8.1"
A Flux HelmRelease that runs real Helm installs and upgrades, with explicit retry and rollback remediation so a failed release does not stall reconciliation waiting for manual intervention.
Who should use Argo CD and who should use Flux? Multi-tenancy, access control and cluster topology
Argo CD suits organizations where a platform team runs deployments as a shared service for many application teams. Flux suits teams that already treat Kubernetes RBAC as their source of truth and are comfortable working from the command line.
| Concern | Argo CD | Flux |
|---|---|---|
| Tenant boundary | AppProjects restrict source repos, destination clusters and namespaces, and resource kinds | Namespaces plus a service account impersonated per Kustomization or HelmRelease |
| Access control | Its own RBAC policies, with SSO through OIDC | Kubernetes RBAC only |
| Developer visibility | Web UI and API showing sync status, diffs and resource trees | flux CLI, kubectl and Kubernetes events |
| Typical topology | Hub-and-spoke: one control plane managing many clusters | Bootstrapped into each cluster, which reconciles itself |
Argo CD's UI is the reason many teams pick it. Developers can see why their service is out of sync without a platform engineer reading logs for them. That convenience has costs. The API server is exposed to users, which adds attack surface. You also run a second authorization system that has to stay aligned with Kubernetes RBAC. With many applications, the repo server and application controller need horizontal scaling or sharding. In a hub-and-spoke setup, the hub holds credentials for every cluster, so compromising it affects all of them.
Flux's impersonation model keeps permissions inside the cluster's own RBAC, which auditors already understand. Without a built-in UI, developers need cluster access and CLI familiarity to diagnose a failed reconciliation. Per-cluster installs also mean that upgrading and monitoring Flux multiplies with every cluster you add.
How do you structure repositories and promote backend services across environments?
Keep application source and deployment config in separate repositories. CI builds the image from the app repo and opens a pull request against the config repo. Your deploy history then becomes a readable log of tag changes, and a code-only commit can't trigger a production rollout. A typical config repo has apps/orders-api/base/ (Deployment, Service, kustomization.yaml) and apps/orders-api/overlays/{dev,staging,prod}/. Each overlay sets replicas, resource limits and the image. The overlay pins the image through the images field: name: registry.example.com/orders-api with newTag: 1.4.2. Promotion is a pull request that copies the tested tag from the staging overlay into the prod overlay. The same layout works with Helm if you swap overlays for values-dev.yaml, values-staging.yaml and values-prod.yaml.
Both tools read this layout the same way: one path per environment.
- Argo CD: An Application points
spec.source.pathat an overlay directory. An ApplicationSet with a Git directory generator overapps/*/overlays/*creates one Application per service per environment, so you don't hand-write each one. - Flux: You define one Kustomization per environment, with
spec.pathset to the overlay and a shared GitRepository as its source.
Add guards before you turn on fully automatic syncing for prod:
- Review rules: Require code-owner review on
overlays/prod/. - Argo CD: Define sync windows in the AppProject to block syncs outside approved hours.
- Flux: Set
spec.suspend: trueon the prod Kustomization, or runflux suspend kustomization, to freeze reconciliation during incidents.
Remove these guards once you trust your rollback path.
# Config repo layout (app code lives in a separate repo):
# apps/orders-api/base/{deployment.yaml,service.yaml,kustomization.yaml}
# apps/orders-api/overlays/{dev,staging,prod}/kustomization.yaml
#
# File: apps/orders-api/overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: orders-prod
resources:
- ../../base
# Promotion PR changes only this tag, copied from the staging overlay
images:
- name: registry.example.com/orders-api
newTag: "1.4.2"
# Prod-specific scale; base keeps a single replica for dev
replicas:
- name: orders-api
count: 3
---
# Flux: one Kustomization per environment, pointing at the overlay path
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: orders-api-prod
namespace: flux-system
spec:
interval: 5m
path: ./apps/orders-api/overlays/prod
prune: true
sourceRef:
kind: GitRepository
name: config-repo
# Guard: set to true to freeze prod reconciliation during an incident
suspend: false
A prod Kustomize overlay that pins the orders-api image tag and sets replicas, plus the Flux Kustomization that reconciles that overlay path and can be suspended as a guard.
How should you handle image updates and secrets with Argo CD or Flux?
Image updates
Flux ships image automation as part of its own toolkit. The image-reflector-controller scans a registry, an ImagePolicy selects a tag (for example, the highest semver in a range), and the image-automation-controller commits that tag to Git at marked fields in your manifests. Argo CD has no built-in equivalent. You either run the separately maintained Argo CD Image Updater or have CI commit the new tag after a successful build.
Committing to Git keeps Git as the record of what is deployed, but it has costs:
- Write access. The bot holds a credential that can push to your config repo. Scope it to a single branch or path, and require pull requests for production.
- Noisy history. Every build creates a commit, which buries the human changes that matter during an incident.
- Merge conflicts. Concurrent bot and human edits to the same file collide. Keep image tags in their own small files to reduce this.
Argo CD Image Updater can also override image parameters on the Application without committing. This avoids the noise, but Git no longer shows what is running.
Secrets
Never store plaintext secrets in Git, even in a private repository.
| Pattern | Flux | Argo CD |
|---|---|---|
| SOPS-encrypted files | Native in kustomize-controller | Requires a config management plugin |
| Sealed Secrets | Works; controller decrypts in-cluster | Works; controller decrypts in-cluster |
| External secret operator | Works; Git holds only references | Works; Git holds only references |
To enable SOPS in Flux, set spec.decryption.provider: sops on the Kustomization and point spec.decryption.secretRef at a Secret that holds the private key.
If you run both tools, use an external secret operator. It behaves the same under each one and keeps secret values out of Git entirely.
Argo CD vs Flux: when should you choose each, and when should you avoid both?
Start with four questions, because they map directly onto how each tool is built.
| Question | Points to Argo CD | Points to Flux |
|---|---|---|
| Do developers need a UI to see sync state and diffs? | Yes, built in | No; CLI, events and metrics suffice |
Do you rely on Helm release semantics (hooks, rollback, helm list)? |
No; charts are rendered to manifests | Yes; helm-controller manages real releases |
| Central or per-cluster control? | One control plane managing many clusters | A controller set inside each cluster |
| How much custom RBAC will you maintain? | AppProjects plus Argo CD's own policy layer | Kubernetes RBAC and service account impersonation |
Engineering cost. Argo CD's API server, SSO integration and policy layer are extra surface you must patch, expose and audit. Holding credentials for every target cluster also makes the hub a high-value target. Flux has no UI to secure. You pay for that with weaker self-service visibility, and someone must build dashboards or alerting instead. Both tools save time in the same areas: drift is corrected automatically, the deployed state can be inspected without shell access, and promotion becomes a reviewed commit rather than a manual step.
Choose deliberately. Switching tools later means rewriting every Application or Kustomization CRD, along with repo layout, promotion conventions and team habits. That cost grows with each service you onboard.
When to skip GitOps. A single small cluster, workflows built on imperative steps such as ordered migrations or manual approvals mid-deploy, or heavy stateful orchestration are often better served by CI running kubectl apply or helm upgrade. This works best with a protected pipeline and a separate drift check.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to argo cd vs flux, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.