Open and extensible continuous delivery solution for Kubernetes. Powered by GitOps Toolkit.
Flux v2.3.0 is a feature release. Users are encouraged to upgrade for the best experience.
For a compressive overview of new features and API changes included in this release, please refer to the Announcing Flux 2.3 GA blog post.
This release marks the General Availability (GA) of Flux Helm features and APIs, including helm-controller, the HelmRelease
, HelmChart
, and HelmRepository
APIs.
The HelmRepository
v2 API comes with new features, such as the ability to reference Helm charts from OCIRepository
sources, reuse existing HelmChart
resources, and verify the integrity of Helm chart artifacts signed with Notary Notation.
❤️ Big thanks to all the Flux contributors that helped us with this release!
This release is compatible with the following Kubernetes versions:
Kubernetes version | Minimum required |
---|---|
v1.28 |
>= 1.28.0 |
v1.29 |
>= 1.29.0 |
v1.30 |
>= 1.30.0 |
[!NOTE] Note that the Flux project offers support only for the latest three minor versions of Kubernetes. Backwards compatibility with older versions of Kubernetes and OpenShift is offered by vendors such as ControlPlane that provide enterprise support for Flux.
The HelmRelease kind was promoted from v2beta2 to v2 (GA).
The v2 API is backwards compatible with v2beta2, with the exception of the deprecated fields which have been removed.
Removed fields:
.spec.chart.spec.valuesFile
replaced by .spec.chart.spec.valuesFiles
..spec.postRenderers.kustomize.patchesJson6902
replaced by .spec.postRenderers.kustomize.patches
..spec.postRenderers.kustomize.patchesStrategicMerge
replaced by .spec.postRenderers.kustomize.patches
..status.lastAppliedRevision
replaced by .status.history.chartVersion
.New fields:
.spec.chartRef
allows referencing chart artifacts from OCIRepository
and HelmChart
objects..spec.chart.spec.ignoreMissingValuesFiles
allows ignoring missing values files instead of failing to reconcile.The HelmChart kind was promoted from v1beta2 to v1 (GA).
The v1 API is backwards compatible with v1beta2, with the exception of the deprecated fields which have been removed.
Removed fields:
.spec.valuesFile
replaced by .spec.chart.valuesFiles
.New fields:
.spec.ignoreMissingValuesFiles
allows ignoring missing values files instead of failing to reconcile..spec.verify.provider: notation
verify the signature of a Helm OCI artifacts using Notation trust policy and CA certificate.The HelmRepository kind was promoted from v1beta2 to v1 (GA).
The v1 API is backwards compatible with v1beta2.
The OCIRepository kind gains new optional fields with no breaking changes.
New fields:
.spec.ref.semverFilter
allows filtering the tags based on regular expressions before applying the semver range..spec.verify.provider: notation
verify the signature of OCI artifacts using Notation trust policy and CA certificate.The Flux Kustomization kind gains new optional fields with no breaking changes.
New fields:
.spec.namePrefix
allows setting a name prefix for the generated resources..spec.nameSuffix
allows setting a name suffix for the generated resources.The ImageUpdateAutomation kind was promoted from v1beta1 to v1beta2.
The v1beta2 API is backwards compatible with v1beta1.
Deprecated fields:
Updated
template data has been deprecated in favour of Changed
that is designed to accommodate for all the types of updates made.New fields:
.spec.policySelector
allows filtering ImagePolicy
based on labels.The Receiver kind gains new optional fields with no breaking changes.
New fields:
.spec.type: cdevents
allows receiving, validating and filtering of CDEvents.Upgrade Flux from v2.x
to v2.3.0
either by rerunning bootstrap or by using the Flux GitHub Action.
For more details, please refer to the upgrade guide from the Announcing Flux 2.3 GA blog post.
HelmRelease
API to v2 (GA)(create|delete|export) source chart
commands--reproducible
flag to flux push artifact
flux reconcile
and flux create
--ssh-hostkey-algos
flag to bootstrap commandGOMAXPROCS
and GOMEMLIMIT
to all Flux controllersflux envsubst
command--strict-substitute
flag to flux build ks
and flux diff ks
--registry-creds
flag to bootstrap and install commandsImageUpdateAutomation
API to v1beta2--force
flag descriptionflux check
should error on unrecognised argsflux stats
should error on unrecognised argsFlux v2.2.3 is a patch release which comes with various fixes and improvements. Users are encouraged to upgrade for the best experience.
:bulb: For upgrading to Flux v2.2, please see the procedure documented in 2.2.0.
This release updates the Kubernetes dependencies to v1.28.6 and various other dependencies to their latest version to patch upstream CVEs.
All controllers are built with Go 1.21.6 using Alpine Linux 3.19.1 base image.
[!NOTE] Due to breaking changes in Helm v3.14.0, the helm-controller version included in this patch release comes with Helm SDK v3.13.3. A preview build of the helm-controller with the latest Helm SDK is available at helm-controller#879.
Fixes:
Roles
and ClusterRoles
with aggregated roles were continuous reconciled by kustomize-controller has been fixed.See the components changelog for a full list of bug fixes.
flux check
should error on unrecognised argsflux stats
should error on unrecognised argsFlux v2.2.2 is a patch release that addresses an issue with the label selector sharding functionality in the helm-controller. Users are encouraged to upgrade for the best experience.
:bulb: For upgrading to Flux v2.2, please see the procedure documented in 2.2.0.
Flux v2.2.1 is a patch release that comes with fixes to API backwards compatibility. Users are encouraged to upgrade for the best experience.
:bulb: For upgrading to Flux v2.2, please see the procedure documented in 2.2.0.
This version was tested with the latest Kubernetes release, and extends Flux support to Kubernetes v1.29.
The Helm SDK was updated to the latest version, v3.13.3.
Logging in kustomize-controller and helm-controller has been improved to provide faster feedback on any HTTP errors encountered while fetching artifacts from source-controller.
Flux v2.2.0 is a feature release. Users are encouraged to upgrade for the best experience.
The Flux CLI and controllers have been updated to Kustomize v5.3.0 and Kubernetes v1.28.4.
Flux helm-controller's reconciliation model underwent a significant overhaul, addressing persistent issues such as the automatic recovery of releases stuck in a pending state. In addition, it improves the observability of the release status, and it introduces the ability to enable drift detection on a per-object basis. For more details on the helm-controller improvements, please see the Announcing Flux 2.2 GA blog post.
The Flux CLI can now be used to force or reset the reconciliation state of a HelmRelease
v2beta2 object using flux reconcile hr --force
and flux reconcile hr --reset
.
Flux CLI comes with support for bootstrapping Gitea repositories and adds guardrails to flux install
and flux bootstrap
to protect users from destructive operations. The flux version
and flux check
commands now print the Flux distribution version deployed on the cluster.
The Flux alerting capabilities have been extended with NATS and Bitbucket Server & Data Center support.
Starting with this release, Flux minor versions are benchmark to measure the Mean Time To Production (MTTP). The results for this version can be found at github.com/fluxcd/flux-benchmark.
:heart: Big thanks to all the Flux contributors that helped us with this release!
This release is compatible with the following Kubernetes versions:
Kubernetes version | Minimum required |
---|---|
v1.26 |
>= 1.26.0 |
v1.27 |
>= 1.27.1 |
v1.28 |
>= 1.28.0 |
Note that Flux may work on older versions of Kubernetes e.g. 1.25, but we don't recommend running end-of-life versions in production nor do we offer support for these versions.
The HelmRelease kind was promoted from v2beta1 to v2beta2.
The v2beta2 API is backwards compatible with v2beta1, the v2beta1 API is deprecated and will be removed in a future release.
Deprecated fields:
.patchesStrategicMerge
and .patchesJson6902
Kustomize post-rendering fields have been deprecated in favor of .patches
..status.lastAppliedRevision
and .status.lastReleaseRevision
fields have been deprecated in favor of .status.history
..status.lastAttemptedValuesChecksum
has been deprecated in favor of .status.lastAttemptedConfigDigest
.New fields:
.spec.driftDetection.mode
field..spec.driftDetection.ignore
.spec.test.filters
field..status.history
field. This includes any Helm test results when enabled..status.lastHandledForceAt
and .status.lastHandledResetAt
fields have been introduced to track the last time a force upgrade or reset was handled.The Alert and Provider kinds were promoted from v1beta2 to v1beta3.
The v1beta3 API is backwards compatible with v1beta2, the .status
field was removed making the resources static objects. Any errors encountered while sending notifications are now recorded as Kubernetes Events associated with the Alert objects.
A new field, .spec.prefix
, has been added to the Bucket API, which enables server-side filtering of files if the object's .spec.provider
is set to generic
, aws
or gcp
.
Two new fields, .spec.verify.matchOIDCIdentity.issuer
and .spec.verify.matchOIDCIdentity.subject
have been added to the HelmChart and OCIRepository APIs. If the image has been keylessly signed via Cosign, these fields can be used to verify the OIDC issuer of the Fulcio certificate and the
OIDC identity's subject respectively.
A new boolean field, .spec.insecure
, has been introduced to the
HelmRepository and ImageRepository APIs, which allows connecting to a non-TLS HTTP container registry. For HelmRepositories it is only considered if the object's .spec.type
is set to oci
.
From this release onwards, HelmRepository objects of type OCI are treated as static objects, i.e. they have an empty status.
Upgrade Flux from v2.x
to v2.2.0
either by rerunning bootstrap or by using the Flux GitHub Action.
To upgrade the APIs, make sure the new CRDs and controllers are deployed, and then change the manifests in Git:
apiVersion: helm.toolkit.fluxcd.io/v2beta2
in the YAML files that contain HelmRelease
definitions.apiVersion: notification.toolkit.fluxcd.io/v1beta3
in the YAML files that contain Alert
and Provider
definitions.Bumping the APIs version in manifests can be done gradually. It is advised to not delay this procedure as the deprecated versions will be removed after 6 months.
flux reconcile hr
context deadline exceeded
errorflux install
from overriding bootrapped clusterflux pull
work for OCI artifacts produced by other toolsFlux v2.1.2
is a patch release which comes with various fixes. Users are encouraged to upgrade for the best experience.
Kustomization
and HelmRelease
resources when the source-controller has restarted and is working on restoring the storage.OCIRepositories
when artifacts contain symlinks.Kustomizations
.flux bootstrap
when the owner doesn't match the identity associated with the given token.flux pull artifact
to fetch OCI artifacts produced by other tools.flux pull
work for OCI artifacts produced by other toolsFlux v2.1.1
is a patch release which comes with various fixes. Users are encouraged to upgrade for the best experience.
source-controller
)..spec.secretRef
(source-controller
).image-automation-controller
).helm-controller
).helm-controller
).nil
artifact before loading Helm charts (helm-controller
).flux
CLI).Flux v2.1.0 is a feature release. Users are encouraged to upgrade for the best experience.
The Flux APIs were extended with new opt-in features in a backwards-compatible manner.
The Flux Git capabilities have been improved with support for Git push options, Git refspec, Gerrit, HTTP/S and SOCKS5 proxies.
The Flux alerting capabilities have been extended with Datadog support.
The Flux controllers come with performance improvements when reconciling Helm repositories with large indexes (80% memory reduction), and when reconciling Flux Kustomizations with thousands of resources (x4 faster server-side apply). The load distribution has been improved when reconciling Flux objects in parallel to reduce CPU and memory spikes.
:heart: Big thanks to all the Flux contributors that helped us with this release!
Flux v2.1.0 comes with support for Kubernetes TLS Secrets when referring to secrets containing TLS certs, and deprecates the usage of caFile
, keyFile
and certFile
keys.
For more details about the TLS changes please see the Kubernetes TLS Secrets section.
Flux v2.1.0 comes with major improvements to the Prometheus monitoring stack. Starting with this version, Flux is leveraging the kube-state-metrics
CRD exporter to report metrics containing rich information about Flux reconciliation status e.g. Git revision, Helm chart version, OCI artifacts digests, etc. The gotk_reconcile_condition
metrics was deprecated in favor of the gotk_resource_info
.
For more details about the new monitoring stack please see the Flux Prometheus metrics documentation and the flux2-monitoring-example repository.
The GitRepository API was extended with the following fields:
.spec.proxySecretRef.name
is an optional field used to specify the name of a Kubernetes Secret that contains the HTTP/S or SOCKS5 proxy settings..spec.verify.mode
now support one of the following values HEAD
, Tag
, TagAndHEAD
.The Kustomization API was extended with two apply policies IfNotPresent
and Ignore
.
Changing the apply behaviour for specific Kubernetes resources, can be done using the following annotations:
Annotation | Default | Values | Role |
---|---|---|---|
kustomize.toolkit.fluxcd.io/ssa |
Override |
- Override - Merge - IfNotPresent - Ignore |
Apply policy |
kustomize.toolkit.fluxcd.io/force |
Disabled |
- Enabled - Disabled |
Recreate policy |
kustomize.toolkit.fluxcd.io/prune |
Enabled |
- Enabled - Disabled |
Delete policy |
The IfNotPresent
policy instructs the controller to only apply the Kubernetes resources if they are not present on the cluster.
This policy can be used for Kubernetes Secrets
and ValidatingWebhookConfigurations
managed by cert-manager,
where Flux creates the resources with fields that are later on mutated by other controllers.
The ImageUpdateAutomation was extended with the following fields:
.spec.git.push.refspec
is an optional field used to specify a Git refspec used when pushing commits upstream..spec.git.push.options
is an optional field used to specify the Git push options to be sent to the Git server when pushing commits upstream.All the Flux APIs that accept TLS data have been modified to adopt Secrets of type
kubernetes.io/tls
. This includes:
.spec.secretRef
has been deprecated in favor of a new field .spec.certSecretRef
.caFile
, keyFile
and certFile
keys in the Secret specified in .spec.certSecretRef
have been deprecated in favor of ca.crt
, tls.key
and tls.crt
.caFile
, keyFile
and certFile
keys in the Secret specified in .spec.certSecretRef
have been deprecated in favor of ca.crt
, tls.key
and tls.crt
..spec.secretRef
using the ca.crt
key, which takes precedence over the caFile
key.Upgrade Flux from v2.0.x
to v2.1.0
either by rerunning bootstrap or by using the Flux GitHub Action.
To upgrade Flux from v0.x
to v2.1.0
please follow the Flux GA upgrade procedure.
This release is compatible with the following Kubernetes versions:
Kubernetes version | Minimum required |
---|---|
v1.25 |
>= 1.25.0 |
v1.26 |
>= 1.26.0 |
v1.27 |
>= 1.27.1 |
v1.28 |
>= 1.28.0 |
Note that Flux may work on older versions of Kubernetes e.g. 1.21, but we don't recommend running end-of-life versions in production nor do we offer support for these versions.
--ssh-rsa-bits
flagopenssl
and sha256sum
$RUNNER_TOOL_CACHE
, support MacOS and Windows, validate checksumFlux v2.0.1
is a patch release which comes with various fixes. Users are encouraged to upgrade for the best experience.
:bulb: For upgrading from Flux v0.x
, please see the procedure documented in 2.0.0.
source-controller
, image-reflector-controller
).kustomize-controller
).flux diff ks --kustomization-file
(flux
CLI).openssl
and sha256sum
$RUNNER_TOOL_CACHE
, support MacOS and Windows, validate checksumThis is the first General Availability (GA) release of Flux v2.
Flux v2.0.0 comes with the promotion of the GitOps related APIs to v1 and adds horizontal scaling & sharding capabilities to Flux controllers. The Git bootstrap capabilities provided by the Flux CLI and by Flux Terraform Provider are now considered stable and production ready.
Starting with this version, the build, release and provenance portions of the Flux project supply chain provisionally meet SLSA Build Level 3.
Flux GA is fully integrated with Kubernetes Workload Identity for AWS, Azure and Google Cloud to facilitate passwordless authentication to OCI sources (container images, OCI artifacts, Helm charts).
The Flux alerting capabilities have been extended with PagerDuty and Google Pub/Sub support. The improved Alert v1beta2 API provides better control over events filtering and allows users to enrich the alerts with custom metadata.
Starting with this version, the Flux CLI and the GA components (source-controller, kustomize-controller and notification-controller) follow the release cadence and support pledge documented in the Flux release specification.
This release is compatible with the following Kubernetes versions:
Kubernetes version | Minimum required |
---|---|
v1.24 |
>= 1.24.0 |
v1.25 |
>= 1.25.0 |
v1.26 |
>= 1.26.0 |
v1.27 |
>= 1.27.1 |
Note that Flux may work on older versions of Kubernetes e.g. 1.19, but we don't recommend running end-of-life versions in production nor do we offer support for these versions.
The following (open-source) extensions & integrations are compatible with this Flux release, starting from the specified minimum version or higher.
Type | Project | Version |
---|---|---|
Flux Web UI | weave-gitops | 0.26.0 |
Terraform integration | tf-controller | 0.15.0 |
The GitRepository kind was promoted from v1beta2 to v1 (GA) and deprecated fields were removed.
The v1 API is backwards compatible with v1beta2, except for the following:
.spec.gitImplementation
was removed.spec.accessFrom
was removed.status.contentConfigChecksum
was removed.status.artifact.checksum
was removed.status.url
was removed (replaced by .status.artifact.url
)The Kustomization kind was promoted from v1beta2 to v1 (GA) and deprecated fields were removed.
A new optional field .spec.commonMetadata
was added to the API for setting labels and/or annotations to all resources part of a Kustomization.
The v1 API is backwards compatible with v1beta2, except for the following:
.spec.validation
was removed.spec.patchesStrategicMerge
was removed (replaced by .spec.patches
).spec.patchesJson6902
was removed (replaced by .spec.patches
)The Receiver kind was promoted from v1beta2 to v1 (GA) and deprecated fields were removed.
The v1 API is backwards compatible with v1beta2, except for the following:
.status.url
was removed (replaced by .status.webhookPath
)Upgrade Flux from v0.x
to v2.0.0
either by rerunning bootstrap or by using the Flux GitHub Action.
To upgrade the APIs from v1beta2, make sure the new CRDs and controllers are deployed, and then change the manifests in Git:
GitRepository
and Kustomization
definitions.apiVersion: source.toolkit.fluxcd.io/v1
in the YAML files that contain GitRepository
definitions.apiVersion: kustomize.toolkit.fluxcd.io/v1
in the YAML files that contain Flux Kustomization
definitions.apiVersion: notification.toolkit.fluxcd.io/v1
in the YAML files that contain Receiver
definitions.GitRepository
and Kustomization
objects present in the .spec.resources
list of Receiver
definitions.Bumping the APIs version in manifests can be done gradually. It is advised to not delay this procedure as the beta versions will be removed after 6 months.
:heart: Big thanks to all the Flux contributors that helped us reach this milestone! :clap: And a special shoutout to the Flux community who supported us over the years!
flux push
example for ECRgo.mod
version with Kubernetes (Go 1.20)flux logs
more lenient