Flux v1 to v2 migration frequently asked questions.

Flux v1 vs v2 questions

What does Flux v2 mean for Flux?

Flux v1 is a monolithic do-it-all operator; Flux v2 separates the functionalities into specialized controllers, collectively called the GitOps Toolkit.

You can install and operate Flux v2 simply using the flux command. You can easily pick and choose the functionality you need and extend it to serve your own purposes.

We went through the following steps for our community:

  1. Put Flux v1 into maintenance mode (no new features being added; bugfixes and CVEs patched only).
  2. Continued work on the Flux v2 roadmap.
  3. We provided transition guides for specific user groups, e.g. users of Flux v1 in read-only mode, or of Helm Operator v1, etc. once the functionality was integrated into Flux v2 and it’s deemed “ready”.
  4. Once the use-cases of Flux v1 were covered, we promised to continue supporting Flux v1 for 6 months.
  5. We finally archived Flux Legacy and Helm Operator.

Why did you rewrite Flux?

Flux v2 implements its functionality in individual controllers, which allowed us to address long-standing feature requests much more easily.

By basing these controllers on modern Kubernetes tooling (controller-runtime libraries), they can be dynamically configured with Kubernetes custom resources either by cluster admins or by other automated tools – and you get greatly increased observability.

This gave us the opportunity to build Flux v2 with the top Flux v1 feature requests in mind:

  • Supporting multiple source Git repositories
  • Operational insight through health checks, events and alerts
  • Multi-tenancy capabilities, like applying each source repository with its own set of permissions

On top of that, testing the individual components and understanding the codebase becomes a lot easier.

What are significant new differences between Flux v1 and Flux v2?


Flux v1Flux v2
Limited to a single Git repositoryMultiple Git repositories
Declarative config via arguments in the Flux deploymentGitRepository custom resource, which produces an artifact which can be reconciled by other controllers
Follow HEAD of Git branchesSupports Git branches, pinning on commits and tags, follow SemVer tag ranges
Suspending of reconciliation by downscaling Flux deploymentReconciliation can be paused per resource by suspending the GitRepository
Credentials config via Arguments and/or Secret volume mounts in the Flux podCredentials config per GitRepository resource: SSH private key, HTTP/S username/password/token, OpenPGP public keys
Ignoring resources with fluxcd.io/ignore: "true" annotationIgnoring resources with kustomize.toolkit.fluxcd.io/reconcile: disabled annotation

kustomize support

Flux v1Flux v2
Declarative config through .flux.yaml files in the Git repositoryDeclarative config through a Kustomization custom resource, consuming the artifact from the GitRepository
Manifests are generated via shell exec and then reconciled by fluxdGeneration, server-side validation, and reconciliation is handled by a specialised kustomize-controller
Reconciliation using the service account of the Flux deploymentSupport for service account impersonation
Garbage collection needs cluster role binding for Flux to query the Kubernetes discovery APIGarbage collection needs no cluster role binding or access to Kubernetes discovery API
Support for custom commands and generators executed by fluxd in a POSIX shellNo support for custom commands

Helm integration

Flux v1Flux v2
Declarative config in a single Helm custom resourceDeclarative config through HelmRepository, GitRepository, Bucket, HelmChart and HelmRelease custom resources
Chart synchronisation embedded in the operatorExtensive release configuration options, and a reconciliation interval per source
Support for fixed SemVer versions from Helm repositoriesSupport for SemVer ranges for HelmChart resources
Git repository synchronisation on a global intervalPlanned support for charts from GitRepository sources
Limited observability via the status object of the HelmRelease resourceBetter observability via the HelmRelease status object, Kubernetes events, and notifications
Resource heavy, relatively slowBetter performance
Chart changes from Git sources are determined from Git metadataChart changes must be accompanied by a version bump in Chart.yaml to produce a new artifact

Notifications, webhooks, observability

Flux v1Flux v2
Emits “custom Flux events” to a webhook endpointEmits Kubernetes events for included custom resources
RPC endpoint can be configured to a 3rd party solution like FluxCloud to be forwarded as notifications to e.g. SlackFlux v2 components can be configured to POST the events to a notification-controller endpoint. Selective forwarding of POSTed events as notifications using Provider and Alert custom resources.
Webhook receiver is a side-projectWebhook receiver, handling a wide range of platforms, is included
Unstructured loggingStructured logging for all components
Custom Prometheus metricsGeneric / common controller-runtime Prometheus metrics

Are there any breaking changes?

  • In Flux v1 Kustomize support was implemented through .flux.yaml files in the Git repository. As indicated in the comparison table above, while this approach worked, we found it to be error-prone and hard to debug. The new Kustomization CR should make troubleshooting much easier. Unfortunately we needed to drop the support for custom commands as running arbitrary shell scripts in-cluster poses serious security concerns.
  • Helm users: we redesigned the HelmRelease API and the automation will work quite differently, so upgrading to HelmRelease v2 will require a little work from you, but you will gain more flexibility, better observability and performance.

In an announcement in August 2019, the expectation was set that the Flux project would integrate the GitOps Engine, then being factored out of ArgoCD. Since the result would be backward-incompatible, it would require a major version bump: Flux v2.

After experimentation and considerable thought, we (the maintainers) have found a path to Flux v2 that we think better serves our vision of GitOps: the GitOps Toolkit. In consequence, we do not now plan to integrate GitOps Engine into Flux.

How can I get involved?

There are a variety of ways and we look forward to having you on board building the future of GitOps together:

Last modified 2023-08-24: Fix API links (db9fb9a)