Reference¶

Scope

Look-up facts for Flux 2.x: release and support matrix, bundled controller versions, every CRD with its served API version, removed APIs, controller ports and default resources, multi-tenancy flags, authentication and notification options, Flux Operator APIs, and the hardening checklist. Facts are pinned to Flux v2.9.5 (2026-08-31) unless a row says otherwise.

Release and Support Matrix¶

Flux ships a minor release roughly two weeks after each Kubernetes minor release (at least three per year). The project supports the last three minor releases. Each new minor supports Kubernetes N-2 (Flux releases policy).

Flux minor	GA date	Latest patch (date)	Kubernetes supported	OpenShift	APIs removed in this minor	Status (2026-09)
2.9	2026-06-30	v2.9.5 (2026-08-31)	1.34, 1.35, 1.36	4.21	`image.toolkit.fluxcd.io/v1beta2`, `notification.toolkit.fluxcd.io/v1beta2`	Supported (current)
2.8	2026-02-24	v2.8.8 (2026-05-20)	1.33, 1.34, 1.35	4.20	`source.toolkit.fluxcd.io/v1beta2`, `kustomize.toolkit.fluxcd.io/v1beta2`, `helm.toolkit.fluxcd.io/v2beta2`	Supported
2.7	2025-09-30	v2.7.5 (2025-11-27)	1.32, 1.33, 1.34	4.19	`source/v1beta1`, `kustomize/v1beta1`, `helm/v2beta1`, `image/v1beta1`, `notification/v1beta1`	Supported until the next minor ships
2.6	2025-05-29	—	—	—	—	End of life (announced with 2.9)
2.5	2025-02-20	—	—	—	—	End of life (announced with 2.8)

Removed APIs block upgrades

Run flux migrate (cluster) or flux migrate -f . (Git checkout) before upgrading to 2.8 or 2.9. The official step-by-step path is Upgrade Procedure for Flux v2.7+. See How-to Guides: Upgrade Flux.

Sources: Flux 2.9 announcement, Flux 2.8 announcement, Flux 2.7 announcement, flux2 releases.

Release Artifacts¶

Every release publishes: CLI binaries (Linux, macOS, Windows), multi-arch CLI images (ghcr.io/fluxcd/flux-cli, docker.io/fluxcd/flux-cli), controller manifests, OCI artifacts with the manifests, an SPDX SBOM, SLSA provenance, and Cosign-signed checksums (Flux releases).

Flux v2.9.5 Component Versions¶

Controller versions bundled in the release/v2.9.x branch of fluxcd/flux2 (manifests/bases/*/kustomization.yaml).

Component	Version	Installed by default	Notes
`source-controller`	v1.9.5	Yes	Helm v4.2.4 (upstream; the temporary Flux fork was dropped in 2.9.5)
`kustomize-controller`	v1.9.5	Yes	Kustomize API v0.21.x
`helm-controller`	v1.6.4	Yes	Helm v4 SDK since Flux 2.8
`notification-controller`	v1.9.4	Yes
`image-reflector-controller`	v1.2.5	Opt-in (`--components-extra`)
`image-automation-controller`	v1.2.5	Opt-in (`--components-extra`)
`source-watcher`	v2.2.4	Opt-in (`--components-extra=source-watcher`)	Serves `ArtifactGenerator`, added in Flux 2.7
Kubernetes libraries	1.36.4	—	`k8s.io/*` v0.36.4

Controllers and CRDs¶

Served (and storage) API version per CRD, read from each controller's config/crd/bases at the tag bundled with Flux v2.9.5. Every CRD serves exactly one version.

Controller	Kind	API version	Purpose
source-controller	`GitRepository`	`source.toolkit.fluxcd.io/v1`	Clone Git at a branch/tag/semver/commit, package as tarball artifact
source-controller	`OCIRepository`	`source.toolkit.fluxcd.io/v1`	Pull OCI artifacts (manifests or Helm charts) from container registries
source-controller	`HelmRepository`	`source.toolkit.fluxcd.io/v1`	Index an HTTP/S Helm repository (or OCI repo, legacy mode)
source-controller	`HelmChart`	`source.toolkit.fluxcd.io/v1`	Package a chart from a HelmRepository, GitRepository or Bucket
source-controller	`Bucket`	`source.toolkit.fluxcd.io/v1`	Fetch objects from S3-compatible storage, GCS, Azure Blob
source-controller	`ExternalArtifact`	`source.toolkit.fluxcd.io/v1`	Artifact produced by a third-party controller (for example source-watcher)
source-watcher	`ArtifactGenerator`	`source.extensions.fluxcd.io/v1beta1`	Compose several sources into one artifact or split a monorepo into many
kustomize-controller	`Kustomization`	`kustomize.toolkit.fluxcd.io/v1`	Build with Kustomize, SOPS-decrypt, substitute, server-side apply, prune, health-check
helm-controller	`HelmRelease`	`helm.toolkit.fluxcd.io/v2`	Install/upgrade/test/rollback/uninstall Helm releases with remediation
notification-controller	`Provider`	`notification.toolkit.fluxcd.io/v1beta3`	Outbound target (Slack, Teams, Git commit status, OTel)
notification-controller	`Alert`	`notification.toolkit.fluxcd.io/v1beta3`	Route events from Flux objects to Providers
notification-controller	`Receiver`	`notification.toolkit.fluxcd.io/v1`	Inbound webhook that triggers reconciliation
image-reflector-controller	`ImageRepository`	`image.toolkit.fluxcd.io/v1`	Scan a registry for tags
image-reflector-controller	`ImagePolicy`	`image.toolkit.fluxcd.io/v1`	Select the latest tag (semver, alphabetical, numerical)
image-automation-controller	`ImageUpdateAutomation`	`image.toolkit.fluxcd.io/v1`	Commit and push tag updates to Git using setter markers

Two API versions still in beta

Alert and Provider remain v1beta3, and ArtifactGenerator is v1beta1 (under the separate source.extensions.fluxcd.io group). Everything else is GA. Referencing an ExternalArtifact from a Kustomization or HelmRelease requires --feature-gates=ExternalArtifact=true on kustomize-controller and helm-controller; flux install/flux bootstrap add this patch automatically when source-watcher is among the components (flux2 pkg/manifestgen/install/templates.go).

API Version History¶

API group	Stable version	Beta versions removed
`source.toolkit.fluxcd.io`	v1 (GitRepository GA in 2.0; OCIRepository GA in 2.6)	v1beta1 (2.7), v1beta2 (2.8)
`kustomize.toolkit.fluxcd.io`	v1 (2.0)	v1beta1 (2.7), v1beta2 (2.8)
`helm.toolkit.fluxcd.io`	v2 (2.3)	v2beta1 (2.7), v2beta2 (2.8)
`image.toolkit.fluxcd.io`	v1 (2.7)	v1beta1 (2.7), v1beta2 (2.9)
`notification.toolkit.fluxcd.io`	v1 for Receiver; v1beta3 for Alert/Provider	v1beta1 (2.7), v1beta2 (2.9)

Note: the "GA in" versions come from the release announcements in fluxcd/website (checked 2026-09-27): GitRepository v1 with Flux 2.0 (GA 2023-07-05), HelmRelease helm.toolkit.fluxcd.io/v2 with 2.3 (2024-05), and OCIRepository v1 with 2.6 (2025-05-29, "General Availability of Flux OCI Artifacts").

Flux Operator APIs¶

The Flux Operator is a separate project from ControlPlane (AGPL-3.0). Latest release v0.60.0 (2026-09-11) (releases).

Kind	API version	Purpose
`FluxInstance`	`fluxcd.controlplane.io/v1`	Declarative install, configure, and upgrade of the Flux controllers (`spec.distribution.version: "2.x"`), plus optional cluster sync (`spec.sync`) from Git, OCI or Bucket
`FluxReport`	`fluxcd.controlplane.io/v1`	Read-only report of Flux readiness, distribution, CRD versions, reconciler stats, sync status
`ResourceSet`	`fluxcd.controlplane.io/v1`	Template a group of Flux and Kubernetes objects over a matrix of inputs (`<< inputs.x >>` syntax)
`ResourceSetInputProvider`	`fluxcd.controlplane.io/v1`	Feed ResourceSet inputs from external systems (for example GitHub pull requests, GitLab merge requests)

Other Flux Operator features: the Flux Web UI (port 9080 on svc/flux-operator, OIDC SSO), the Flux MCP Server for AI assistants, and a flux-operator CLI (README).

Ports and Default Resources¶

From each controller's config/manager/deployment.yaml at the version bundled with Flux v2.9.5.

Controller	Ports	CPU request / limit	Memory request / limit	Volumes
source-controller	9090 `http` (artifact server), 8080 metrics, 9440 healthz	50m / 1000m	64Mi / 1Gi	`/data` emptyDir (artifacts), `/tmp` emptyDir
kustomize-controller	8080 metrics, 9440 healthz	100m / 1000m	64Mi / 1Gi	`/tmp` emptyDir
helm-controller	8080 metrics, 9440 healthz	100m / 1000m	64Mi / 1Gi	`/tmp` emptyDir
notification-controller	9090 `http` (events), 9292 `http-webhook` (Receivers), 8080 metrics, 9440 healthz	100m / 1000m	64Mi / 1Gi	`/tmp` emptyDir
image-reflector-controller	8080 metrics, 9440 healthz	100m / 1000m	64Mi / 1Gi	`/tmp` emptyDir
image-automation-controller	8080 metrics, 9440 healthz	100m / 1000m	64Mi / 1Gi	`/tmp` emptyDir
source-watcher	9090 `http` (artifact server), 8080 metrics, 9440 healthz	50m / 1000m	64Mi / 1Gi	`/data` emptyDir

Performance and Scaling¶

Reconciliation Profiles¶

Not published: the flux2 project publishes no official per-object scaling limits or reconciliation benchmarks (checked 2026-09-27). Earlier versions of this page carried object counts per cluster labelled "tested" and "recommended" with no source or test conditions; they were removed on 2026-09-27. Size with the documented levers below and measure controller CPU, memory and queue depth on your own workload.

Scaling Levers (Documented)¶

Lever	Where	Effect
`--concurrent`	each controller	Number of parallel reconciles per controller
Interval jitter	controller flag (see each controller's options page)	Spreads objects that share the same `spec.interval`
Sharding	label `sharding.fluxcd.io/key` + extra controller replicas	Splits objects across controller instances (Flux sharding)
`cluster.size` / sharding in `FluxInstance`	Flux Operator	Operator presets for vertical scaling and shards (Flux Operator docs)
`GitRepository.spec.sparseCheckout`	source-controller	Checks out only listed directories
`GitRepository.spec.ignore` / `.sourceignore`	source-controller	Shrinks the packaged artifact (fetch still full)

Multi-Tenancy Lockdown Flags¶

From Flux multi-tenancy lockdown.

Flag	Controllers	Effect
`--no-cross-namespace-refs=true`	kustomize-, helm-, notification-, image-reflector-, image-automation-controller	Objects can only reference sources and events in their own namespace
`--no-remote-bases=true`	kustomize-controller	Blocks Kustomize remote bases, so only Flux sources can change cluster state
`--default-service-account=default`	kustomize-, helm-controller	Objects without `spec.serviceAccountName` impersonate the tenant namespace's `default` SA (no permissions)
`spec.serviceAccountName: kustomize-controller` on the `flux-system` Kustomization	—	Keeps the platform-admin sync running with cluster-admin

GitRepository Authentication¶

From the GitRepository v1 spec.

Method	Configuration	Typical use
SSH	Secret with `identity` (private key) and `known_hosts`	Deploy keys created by `flux bootstrap`
HTTPS basic auth	Secret with `username`, `password` (PAT)	GitHub/GitLab PATs, self-hosted Git
HTTPS bearer token	Secret with `bearerToken`	Token-only Git servers
HTTPS mTLS / custom CA	Secret with `tls.crt`, `tls.key`, `ca.crt`	Private Git servers
GitHub App	`spec.provider: github` + Secret with `githubAppID`, `githubAppPrivateKey`, and one of `githubAppInstallationID` / `githubAppInstallationOwner` (`githubAppBaseURL` for GHES)	Short-lived installation tokens, no user PAT
Azure DevOps Workload Identity	`spec.provider: azure` (+ optional `spec.serviceAccountName`)	Keyless on AKS
AWS CodeCommit Workload Identity	`spec.provider: aws`	Keyless on EKS (new in 2.9)

Git commit verification (spec.verify.mode: HEAD, Tag, TagAndHEAD) accepts PGP public keys (*.asc keys) and, since 2.9, SSH public keys (*.sshpub keys).

OCIRepository Verification¶

Provider	Key material	Notes
`cosign` (key-based)	Secret with `*.pub` keys
`cosign` (keyless)	`spec.verify.matchOIDCIdentity` (`issuer`, `subject` regex)	Custom Sigstore trusted root for self-hosted Rekor/Fulcio since 2.9; Cosign v3 since 2.8
`notation`	Secret with trust policy and CA certs	Notary Project signatures

SOPS Decryption Backends¶

Kustomization.spec.decryption.provider supports only sops (Kustomization spec).

Backend	Secret entry / auth	Notes
age	key ending in `.agekey`	Recommended. Post-quantum age cipher supported since 2.9
OpenPGP	key ending in `.asc`	Legacy
AWS KMS	static credentials or Workload Identity (`spec.decryption.serviceAccountName`)
Azure Key Vault	static credentials or Workload Identity
GCP KMS	static credentials or Workload Identity
OpenBao / HashiCorp Vault	token, or Kubernetes auth via Workload Identity (2.9)

Controller-global decryption (one key set for all Kustomizations) exists for age keys (2.7) and cloud KMS / Vault.

Notification Provider Types¶

Provider.spec.type values in notification-controller v1.9.4: alertmanager, azuredevops, bitbucket, bitbucketserver, datadog, discord, forwarder, gitea, github, githubdispatch, gitlab, grafana, matrix, msteams, opsgenie, pagerduty, rocket, sentry, slack, webex, zulip, otel. Flux 2.8 added PR/MR comment providers githubpullrequestcomment, gitlabmergerequestcomment and giteapullrequestcomment (Flux 2.8 announcement).

Receiver.spec.type values: generic, generic-hmac, generic-oidc (2.9), github (also used for Gitea), gitlab, bitbucket (Bitbucket Server), harbor, dockerhub, quay, nexus, acr, gcr, cdevents (Receiver spec).

Feature Gates of Note¶

Feature gate	Controller(s)	Default (v2.9.5)	Purpose
`CancelHealthCheckOnNewRevision`	kustomize-controller (2.7), helm-controller (2.8)	Off	Abort running health checks when a new revision or spec change arrives
`DefaultToRetryOnFailure`	helm-controller	Off	Retry-on-failure remediation by default; recommended with the gate above
`UseHelm3Defaults`	helm-controller	Off	Restore Helm 3 behaviour: client-side apply, legacy readiness, `nohooks` post-render
`ExternalArtifact`	kustomize-controller, helm-controller	Off (auto-enabled by the CLI when source-watcher is installed)	Allow `ExternalArtifact` source references (needed for ArtifactGenerator output)
`DisableChartDigestTracking`	helm-controller	Off	Stop appending the OCI digest to the chart version
`StrictPostBuildSubstitutions`	kustomize-controller	On (opt-out since 2.9)	Fail on unresolved `${VAR}` substitutions without defaults
`GitSparseCheckout`	image-automation-controller	Off	Sparse checkout for ImageUpdateAutomation clones (2.7)
`GitShallowClone`, `GitAllBranchReferences`, `GitForcePushBranch`	image-automation-controller	On	Git behaviour of image automation

Defaults read from each controller's internal/features/features.go at the bundled tag.