Quick summary: Flux v2 is the production GitOps engine of choice for many Kubernetes platform teams in 2026. CNCF graduated, mature, and broadly adopted. Done well, GitOps with Flux gives you fully auditable deployments, automatic drift correction, and clean multi-tenant separation. Done poorly, it becomes a tangle of overly-permissive Kustomizations and broken secret rotation. This guide covers the repository structure that scales, multi-tenant isolation that survives organic growth, the secret management options and their tradeoffs, image automation patterns, and the operational practices that make Flux genuinely reliable in production.
Why Flux v2 Specifically
The Kubernetes GitOps ecosystem in 2026 is dominated by two tools: Argo CD and Flux v2. Both are mature, both are CNCF graduated, both are excellent. The choice between them comes down to operational philosophy:
- Argo CD is application-centric. Strong UI, multi-cluster from a single control plane, optimized for developer self-service.
- Flux v2 is platform-centric. Composable controllers (Source, Kustomize, Helm, Image, Notification), runs in each cluster, optimized for platform-team-managed multi-tenancy.
For a platform team operating Kubernetes for many internal teams, Flux v2 is usually the right fit — its controller composition gives you finer control over which tenant can do what. For an application team deploying its own workloads, Argo CD's UX is usually friendlier. Many organizations run both: Flux for platform-managed cluster components, Argo for application teams.
The Three Repository Patterns
Pattern 1: Mono-repo (single repo for everything)
One Git repository contains all manifests for all environments and all tenants. Flux watches the repo, applies subpaths to corresponding clusters and namespaces.
Pros: simplest mental model, atomic cross-tenant changes possible, easy to reason about at small scale.
Cons: blast radius is huge, access control is per-repo (not per-tenant), repo size grows quickly.
Best for: small teams, single-organization deployments, fewer than ~20 tenants.
Pattern 2: Repo-per-tenant
Each tenant has its own Git repo containing their manifests. Platform team has a separate "fleet" repo defining which tenant repos to sync to which clusters.
Pros: clean access control (tenant repo permissions = tenant access), small per-tenant blast radius, scales to hundreds of tenants.
Cons: more moving parts, harder to make platform-wide changes (each tenant repo must update).
Best for: platform teams serving many internal customers, organizations with strong tenant isolation requirements.
Pattern 3: Hybrid (platform repo + tenant repos)
Platform team owns a repo with cluster-wide config, namespace definitions, RBAC, and policy. Each tenant team owns their own repo with their workloads.
Pros: clean separation between platform and application concerns, scales to large organizations.
Cons: requires Flux multi-source configuration (more YAML), tenant repos need careful CODEOWNERS-style review.
Best for: most production deployments above ~10 tenants. The recommended default in 2026.
The Hybrid Pattern in Detail
The recommended directory structure for the platform repo:
platform-flux/
├── clusters/
│ ├── prod-eu-west-1/
│ │ ├── flux-system/ # Flux's own bootstrap manifests
│ │ ├── infrastructure/ # cert-manager, ingress, monitoring, etc.
│ │ └── tenants/ # Per-tenant Flux Source + Kustomization
│ └── prod-us-east-1/
│ └── ...
└── infrastructure/ # Shared cluster infrastructure as Kustomizations
├── base/
└── overlays/Per-tenant configuration in the platform repo defines the GitRepository (pointing to the tenant's repo) and the Kustomization (defining where in that repo to sync from):
---
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
name: tenant-acme
namespace: tenant-acme
spec:
interval: 1m
url: https://github.com/acme/k8s-manifests.git
ref:
branch: main
secretRef:
name: tenant-acme-deploy-key
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: tenant-acme
namespace: tenant-acme
spec:
interval: 5m
path: ./clusters/prod-eu-west-1
prune: true
sourceRef:
kind: GitRepository
name: tenant-acme
serviceAccountName: tenant-acme-flux # Critical: tenant-scoped SAThe serviceAccountName field is the foundation of multi-tenant isolation. Each tenant's Kustomization runs as a tenant-specific service account with RBAC limited to that tenant's namespace. Without this, every tenant's Flux apply has cluster-admin equivalent privileges (wrong default).
Multi-Tenant Isolation: The RBAC That Matters
The minimum tenant-scoped RBAC for a tenant service account:
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: tenant-acme-flux
namespace: tenant-acme
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: tenant-acme-flux
namespace: tenant-acme
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: edit
subjects:
- kind: ServiceAccount
name: tenant-acme-flux
namespace: tenant-acmeThis grants the tenant the standard edit ClusterRole — but only within their own namespace. They cannot create ClusterRoleBindings, modify cluster-scoped resources, or affect other tenants' namespaces.
The harder cases
Some workloads need cluster-scoped resources (CRDs, validating webhooks, etc.). For these, the platform team's Kustomization (running with elevated privileges) provisions the cluster-scoped resources, and the tenant Kustomization only handles namespace-scoped workloads. This separation is the most important platform-engineering pattern in multi-tenant Kubernetes.
Tenant requests for cluster-scoped resources go through a PR review process against the platform repo — slower, but auditable and safe.
Secret Management Options
You can't put plaintext secrets in Git. Three real options:
SOPS + age (recommended for most teams)
Encrypt secrets at rest with age (modern, simple) keys. Flux decrypts at apply time using cluster-side keys.
# Create age key pair (private key kept in cluster, public key in repo)
age-keygen -o age.agekey
# Encrypt a secret in your repo
sops --encrypt --age $AGE_PUBLIC_KEY secret.yaml > secret.enc.yaml
# Configure Flux to decrypt
spec:
decryption:
provider: sops
secretRef:
name: sops-agePros: simple, auditable, key management is one secret in the cluster.
Cons: rotating the master key requires re-encrypting all secrets in the repo.
External Secrets Operator + cloud KMS
Secrets live in AWS Secrets Manager / GCP Secret Manager / HashiCorp Vault. ESO syncs them into Kubernetes Secret resources.
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
name: db-password
namespace: tenant-acme
spec:
secretStoreRef:
name: aws-secrets-manager
kind: ClusterSecretStore
target:
name: db-password
data:
- secretKey: password
remoteRef:
key: tenant-acme/db-passwordPros: secrets never touch Git, leverage existing cloud secret stores, easy rotation.
Cons: dependency on cloud secret store, IAM/auth complexity.
Sealed Secrets (Bitnami)
Encrypt secrets with cluster-public-key, store in Git, controller decrypts on apply.
kubeseal --format yaml < secret.yaml > sealed-secret.yamlPros: simple, established.
Cons: harder to recover if cluster's sealing key is lost; less popular than SOPS in 2026.
Image Automation
Flux can automatically update image references in Git when new image tags appear in the registry. This closes the GitOps loop for application updates without requiring application teams to write commits manually.
---
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
metadata:
name: myapp
namespace: tenant-acme
spec:
image: myregistry.io/tenant-acme/myapp
interval: 5m
---
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
name: myapp
namespace: tenant-acme
spec:
imageRepositoryRef:
name: myapp
policy:
semver:
range: ">=1.0.0 <2.0.0"
---
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageUpdateAutomation
metadata:
name: myapp
namespace: tenant-acme
spec:
interval: 5m
sourceRef:
kind: GitRepository
name: tenant-acme
git:
commit:
author:
email: flux@example.com
name: Flux
messageTemplate: 'chore: bump {{ .ImageRepo }} to {{ .NewTag }}'
push:
branch: mainResult: when a new image tag is pushed to the registry that matches the policy, Flux commits an updated reference to the Git repo, then reconciles it into the cluster. End-to-end deploy from CI image push to running pod takes 5-10 minutes.
Drift Detection and Remediation
One of GitOps's quiet superpowers: when someone applies a manual change to the cluster (kubectl apply, manual scaling), Flux detects the drift and reverts it on the next reconcile.
This is enabled by default with prune: true. The implications matter operationally:
- "kubectl edit" stops working as a real change vector. Every change must go through Git.
- HPA-managed replica counts work correctly because Flux ignores managed-fields it does not own.
- Rapid manual debugging (e.g., temporarily increasing replicas) gets reverted in 5 minutes.
For most teams this is the right default. For specific workloads that need manual flexibility, you can scope Flux's reconciliation more narrowly using spec.targetNamespace or by excluding specific resources.
Operational Patterns That Matter
1. Notification configuration
Flux's notification controller pushes events to Slack, Discord, Microsoft Teams, generic webhooks, or to systems like PagerDuty. Configure it on day one — silent failures in GitOps are dangerous.
apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Provider
metadata:
name: slack
namespace: flux-system
spec:
type: slack
channel: gitops-alerts
secretRef:
name: slack-webhook
---
apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Alert
metadata:
name: production-alerts
namespace: flux-system
spec:
providerRef:
name: slack
eventSeverity: error
eventSources:
- kind: Kustomization
name: '*'2. Use Flagger for progressive delivery
Flagger is the canary-deployment companion to Flux. Define a Canary CRD that progressively shifts traffic from old version to new, monitoring metrics. Automatic rollback on metric regression. Worth adopting once you have the GitOps basics solid.
3. Suspend before maintenance
Before running maintenance scripts that may temporarily diverge from Git, suspend the relevant Kustomizations:
flux suspend kustomization tenant-acme -n tenant-acme
# ... do your manual work ...
flux resume kustomization tenant-acme -n tenant-acme4. Monitor reconciliation status
The flux Prometheus metrics include reconciliation duration, success/failure counts, and last reconcile timestamp. Alert on "no successful reconcile for 30 minutes" — this catches both Git connectivity failures and apply failures.
5. Disaster recovery
Cluster gone, need to rebuild? With proper GitOps: provision new cluster, bootstrap Flux, point at the same Git repo, wait for reconciliation. Time to full restore: 15-30 minutes for a typical cluster. Test this quarterly — the cost of testing is one cluster rebuild; the cost of needing it and finding it broken is days.
Migrating From Argo CD or Manual kubectl
For teams coming from Argo CD: the conceptual model is similar but the operational model differs. Argo's Application CRD maps roughly to Flux's GitRepository + Kustomization pair. Argo's Projects map to Flux's namespace-scoped Kustomizations with RBAC. The migration is mostly mechanical translation; budget 2-4 hours per Application CRD, including testing.
For teams coming from manual kubectl-driven deploys: the harder migration. Existing manual changes need to be discovered, codified into Git, and reconciled. The pattern that works: use kubectl get -o yaml to dump current state, clean up the output (remove generated fields like resourceVersion, uid, status), and commit to Git. Once Git matches reality, switch on Flux reconciliation. Expect 2-4 weeks for a non-trivial cluster; the discovery phase is where most of the time goes.
Frequently Asked Questions
Can Flux deploy to multiple clusters from one Git repo?
Yes — common pattern is one repo with /clusters/<cluster-name>/ subdirectories. Each cluster's Flux instance watches its own subpath. Cleaner than the alternative.
How does Flux handle CRD ordering?
Kustomization has a dependsOn field — declare that Kustomization B depends on A, and Flux orders them. Use it for CRDs (deploy CRD before resources that use it).
What about Helm?
Flux has first-class Helm support via the HelmRelease CRD. Define charts in Git, Flux installs/upgrades them. Many teams use Kustomize for first-party manifests and HelmRelease for third-party software (operators, ingress, monitoring).
Does Flux support Argo CD ApplicationSets?
Not natively. Flux's equivalent is GitRepository + Kustomization with substitution variables. Different mental model; equally powerful for the multi-cluster fleet case.
How do we handle secrets that absolutely cannot be in Git, even encrypted?
External Secrets Operator with cloud KMS or Vault. The secret never lives in the repo at all; only the reference does.
What's the upgrade path?
Flux releases minor versions roughly every 6-8 weeks. Backward compatibility is good. flux upgrade handles the bootstrap update; CRDs migrate automatically. Production teams typically run N-1 to give time for stability validation.
One Real Multi-Tenant Setup
A platform team we know runs Flux v2 across 12 production Kubernetes clusters serving roughly 80 internal product teams. The setup: one platform-flux repo (controlled by the platform team) defining cluster infrastructure and per-tenant GitRepository resources; 80 tenant repositories, each owned by the corresponding product team; Flux deployed per cluster with separate service accounts per tenant; SOPS-encrypted secrets in tenant repos; ESO for cloud-managed secrets where appropriate. Total operational headcount on the GitOps system: 1.5 FTE platform engineers. Mean time from PR merge to production deployment: 6 minutes. Drift incidents per month: 3-5 (all caught and reverted automatically). Tenant onboarding time: 30 minutes for the platform team to add the GitRepository CRD and RBAC, after which the tenant operates self-service. Total system uptime over the past year: 99.97%, with the few outages being cloud provider issues unrelated to Flux itself. Net assessment: the team considers GitOps a permanent architectural choice, not something they would consider replacing.
Further Reading from the Dargslan Library
- DevOps & Cloud category — Kubernetes, GitOps, deployment patterns, and platform engineering.
- Security & Hardening category — RBAC, secret management, and multi-tenant isolation.
- Free cheat sheet library — printable references for flux CLI, kustomize, and Helm operations.
- Dargslan eBook library — comprehensive Kubernetes and DevOps courses.
The Bottom Line
Flux v2 is the right GitOps engine for platform teams in 2026 — mature, composable, and excellent at multi-tenant separation. Done well, it gives you fully auditable deployments, automatic drift correction, and a clean self-service model for application teams. The investment in repository structure and RBAC discipline early pays back many times over in operational simplicity. Start with the hybrid platform/tenant pattern, take secret management seriously from day one, and treat the Git repository as the genuine source of truth — never bypass it for "quick fixes."
