Releases: fluxcd/flux2
v2.3.0
Highlights
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!
Kubernetes compatibility
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.
API changes
HelmRelease v2
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 fromOCIRepository
andHelmChart
objects..spec.chart.spec.ignoreMissingValuesFiles
allows ignoring missing values files instead of failing to reconcile.
HelmChart v1
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.
HelmRepository v1
The HelmRepository kind was promoted from v1beta2 to v1 (GA).
The v1 API is backwards compatible with v1beta2.
OCIRepository 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.
Kustomization v1
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.
ImageUpdateAutomation v1beta2
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 ofChanged
that is designed to accommodate for all the types of updates made.
New fields:
.spec.policySelector
allows filteringImagePolicy
based on labels.
Receiver v1
The Receiver kind gains new optional fields with no breaking changes.
New fields:
.spec.type: cdevents
allows receiving, validating and filtering of CDEvents.
Upgrade procedure
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.
Components changelog
- source-controller v1.3.0
- kustomize-controller v1.3.0
- notification-controller v1.3.0
- helm-controller v1.0.0 v1.0.1
- image-reflector-controller v0.32.0
- image-automation-controller v0.38.0
New Documentation
- HelmRelease v2 specification
- ImageUpdateAutomation v1beta2 specification
- Oracle VBS bootstrap guide
- Azure DevOps bootstrap guide for SSH RSA SHA-2
- OpenShift installation guide and SCC configuration
- Air-gapped installation guide for private container registries
- Bootstrap with Terraform examples
- Flux hub-and-spoke example repository
- Flux CD Architecture Overview blog post
CLI Changelog
- PR #4783 - @stefanprodan - ci: Consolidate conformance tests
- PR #4781 - @stefanprodan - Set Kubernetes 1.28 as min required version
- PR #4780 - @stefanprodan - Update helm-controller to v1.0.1
- PR #4779 - @fluxcdbot - Update toolkit components
- PR #4778 - @darkowlzz - tests/integration: Run flux check after installation
- PR #4777 - @stefanprodan - Add k3s to the conformance test suite
- PR #4775 - @stefanprodan - Update
HelmRelease
API to v2 (GA) - PR #4773 - @makkes - Add
(create|delete|export) source chart
commands - PR #4771 - @matheuscscp - Add 2.3.x release label
- PR #4770 - @stefanprodan - Update Flux architecture diagram
- PR #4769 - @frekw - Add
--reproducible
flag toflux push artifact
- PR #4768 - @stefanprodan - Improve end-to-end test workflow
- PR #4766 - @souleb - Add support for HelmRelease v2 in
flux reconcile
andflux create
- PR #4764 - @stefanprodan - ci: Adapt image automation test to v1beta2
- PR #4759 - @stefanprodan - Update Helm Source APIs to v1 (GA)
- PR #4754 - @stefanprodan - Add
--ssh-hostkey-algos
flag to bootstrap command - PR #4747 - @stefanprodan - Update dependencies to Kubernetes 1.30
- PR #4746 - @swade1987 - Specifying go version in setup-go github action.
- PR #4736 - @dependabot[bot] - build(deps): bump the ci group with 4 updates
- PR #4735 - @JasonTheDeveloper - feat(secret): add create notation secret handler
- PR #4734 - @stefanprodan - Run conformance tests for Kubernetes 1.30.0
- PR #4729 - @stefanprodan - Add OpenShift to the conformance test suite
- PR #4728 - @toomaj - bootstrap: Add support for Git HTTP/S authorization header
- PR #4727 - @makkes - Add flags for issuer/subject OCI signature verification
- PR #4717 - @hawwwdi - Set
GOMAXPROCS
andGOMEMLIMIT
to all Flux controllers - PR #4710 - @stefanprodan - Add
flux envsubst
command - PR #4709 - @stefanprodan - Add
--strict-substitute
flag toflux build ks
andflux diff ks
- PR #4706 - @stefanprodan - Add
--registry-creds
flag to bootstrap and install commands - PR #4705 - @stefanprodan - Update dependencies to Kustomize v5.4.0
- PR #4701 - @fluxcdbot - Update toolkit components
- PR #4699 - @stefanprodan - Update dependencies to Go 1.22 and Kubernetes 1.29.3
- PR #4689 - @makkes - Pin envtest version
- PR #4687 - @carlpett - Add permissions required for flow control
- PR #4678 - @darkowlzz - Update
ImageUpdateAutomation
API to v1beta2 - PR #4666 - @stefanprodan - Mark RFC-0006 as implementable
- PR #4657 - @stefanprodan - ci: Include all go modules in snyk testing
- PR #4654 - @stefanprodan - Remove deprecated e2e tests
- PR #4629 - @rishinair11 - Fix a typo in
--force
flag description - PR #4620 - @stefanprodan - Update Equinix ARM64 GitHub runners
- PR #4610 - @takp - Fix typo in build.go
- PR #4589 - @stefanprodan - Update dependencies
- PR #4583 - @fluxcdbot - Update toolkit components
- PR #4575 - @stefanprodan - Update dependencies to Kubernetes v1.28.6
- PR #4558 - @twinguy -
flux check
should error on ...
v2.2.3
Highlights
Flux v2.2.3 is a patch release which comes with various fixes and improvements. Users are encouraged to upgrade for the best experience.
💡 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:
- Reconciling empty directories and directories without Kubernetes manifests no longer results in an error. This regressing bug was introduced with the kustomize-controller upgrade to Kustomize v5.3 and has been fixed in this patch release.
- The regression due to which
Roles
andClusterRoles
with aggregated roles were continuous reconciled by kustomize-controller has been fixed. - Fix the Git revision displaying when notification-controller sends alerts to Grafana.
- The HelmRelease status reporting has been improved by ensuring that the stale failure conditions get updated after failure recovery.
See the components changelog for a full list of bug fixes.
Components changelog
- source-controller v1.2.4
- kustomize-controller v1.2.2
- notification-controller v1.2.4
- helm-controller v0.37.4
- image-reflector-controller v0.31.2
- image-automation-controller v0.37.1
CLI Changelog
- PR #4589 - @stefanprodan - Update dependencies
- PR #4585 - @dependabot[bot] - build(deps): bump the ci group with 3 updates
- PR #4583 - @fluxcdbot - Update toolkit components
- PR #4575 - @stefanprodan - Update dependencies to Kubernetes v1.28.6
- PR #4573 - @dependabot[bot] - build(deps): bump the ci group with 5 updates
- PR #4558 - @twinguy -
flux check
should error on unrecognised args - PR #4557 - @twinguy -
flux stats
should error on unrecognised args - PR #4554 - @dependabot[bot] - build(deps): bump the ci group with 3 updates
- PR #4553 - @twinguy - Properly detect unexpected arguments during uninstall
- PR #4535 - @dependabot[bot] - build(deps): bump github.com/cloudflare/circl from 1.3.6 to 1.3.7
- PR #4533 - @darkowlzz - tests/int: Add separate resource cleanup step
v2.2.2
Highlights
Flux 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.
💡 For upgrading to Flux v2.2, please see the procedure documented in 2.2.0.
Components changelog
- helm-controller v0.37.2
CLI Changelog
- PR #4505 - @hiddeco - Update helm-controller to v0.37.2 in tests
- PR #4501 - @fluxcdbot - Update toolkit components
- PR #4499 - @stuebingerb - Fix typo in Git bootstrap
- PR #4495 - @dependabot[bot] - build(deps): bump golang.org/x/crypto from 0.16.0 to 0.17.0 in /tests/integration
- PR #4494 - @dependabot[bot] - build(deps): bump golang.org/x/crypto from 0.16.0 to 0.17.0
- PR #4493 - @dependabot[bot] - build(deps): bump golang.org/x/crypto from 0.16.0 to 0.17.0 in /tests/azure
- PR #4491 - @dependabot[bot] - build(deps): bump the ci group with 3 updates
v2.2.1
Highlights
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.
💡 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.
Components changelog
- source-controller v1.2.3
- kustomize-controller v1.2.1
- notification-controller v1.2.3
- helm-controller v0.37.1
CLI Changelog
- PR #4488 - @hiddeco - tests: update API dependencies
- PR #4484 - @stefanprodan - Run conformance tests for Kubernetes v1.29.0
- PR #4483 - @fluxcdbot - Update toolkit components
- PR #4481 - @hoexter - Remove duplicate part of the reconcile hr --reset help message
- PR #4478 - @stefanprodan - Remove deprecated monitoring configs
- PR #4476 - @hiddeco - Properly detect unsupported API errors
- PR #4468 - @hiddeco - Add 2.2.x backport label
v2.2.0
Highlights
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.
❤️ Big thanks to all the Flux contributors that helped us with this release!
Kubernetes compatibility
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.
API changes
HelmRelease v2beta2
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:
- The
.patchesStrategicMerge
and.patchesJson6902
Kustomize post-rendering fields have been deprecated in favor of.patches
. - The
.status.lastAppliedRevision
and.status.lastReleaseRevision
fields have been deprecated in favor of.status.history
. - The
.status.lastAttemptedValuesChecksum
has been deprecated in favor of.status.lastAttemptedConfigDigest
.
New fields:
- Drift detection and correction is now enabled on a per-release basis using the
.spec.driftDetection.mode
field. - Ignoring specific fields during drift detection and correction is now supported using the
.spec.driftDetection.ignore
- Helm tests can now be selectively run using the
.spec.test.filters
field. - A history of metadata from Helm releases up to the previous successful release is now available in the
.status.history
field. This includes any Helm test results when enabled. - The
.status.lastHandledForceAt
and.status.lastHandledResetAt
fields have been introduced to track the last time a force upgrade or reset was handled.
Alert and Provider v1beta3
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.
Bucket v1beta2
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
.
OCIRepository and HelmChart v1beta2
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.
HelmRepository and ImageRepository v1beta2
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 procedure
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:
- Set
apiVersion: helm.toolkit.fluxcd.io/v2beta2
in the YAML files that containHelmRelease
definitions. - Set
apiVersion: notification.toolkit.fluxcd.io/v1beta3
in the YAML files that containAlert
andProvider
definitions. - Commit, push and reconcile the API version changes.
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.
New Documentation
Components changelog
- source-controller v1.2.2
- kustomize-controller v1.2.0
- notification-controller v1.2.2
- helm-controller v0.37.0
- image-reflector-controller v0.31.1
- image-automation-controller v0.37.0
CLI Changelog
- PR #4467 - @stefanprodan - Drop support for Kubernetes EOL versions
- PR #4465 - @stefanprodan - build: Update alpine and kubectl in flux-cli image
- PR #4464 - @souleb - Update go-git-providers to v0.19.2
- PR #4463 - @stefanprodan - Update Git dependencies
- PR #4461 - @fluxcdbot - Update toolkit components
- PR #4455 - @chewong - Fix typos in flux bootstrap documentation
- PR #4454 - @fluxcdbot - Update toolkit components
- PR #4437 - @stefanprodan - Add force and reset flags to
flux reconcile hr
- PR #4433 - @darkowlzz - Update Helm OCI RFC - static HelmRepository design
- PR #4424 - @somtochiama - Show distribution name in flux check and flux version
- PR #4422 - @somtochiama - bootstrap: More details for
context deadline exceeded
error - PR #4416 - @stefanprodan - Update dependencies to Kubernetes v1.28
- PR #4409 - @somtochiama - Make events cmd work well with lowercased and only kind selector
- PR #4404 - @VinGarcia - Fix flux install command so it returns an error when unexpected arguments are passed
- PR #4402 - @mclarke47 - fix build_artifact.go typo
- PR #4388 - @stefanprodan - [RFC-0003] OIDC identity matching for keyless verification
- PR #4382 - @darkowlzz - tests/int: Set exit code 1 on tf destroy fail
- PR #4380 - @hiddeco - Tweak permissions on created files
- PR #4355 - @somtochiama - Confirm before overriding installation by another manager
- PR #4345 - @somtochiama - Prevent
flux install
from overriding bootrapped cluster - PR #4332 - @matheuscscp - Add CLI flags for OCIRepository signature verification
- PR #4329 - @hiddeco - Address various issues throughout code base
- PR #4324 - @somtochiama - bootstrap: Fix error msg when the Git token doesn't match the repo owner
- PR #4323 - @stefanprodan - e2e: Update Go dependencies
- PR #4317 - @Jaykul - Correct "sync" to "component" in log lines
- PR #4313 - @fluxcdbot - Update toolkit components
- PR #4311 - @darkowlzz - Check readiness of Flux kinds using kstatus
- PR #4298 - @darkowlzz - Add support for HelmRepo OCI and NC v1beta3 static objects
- PR #4296 - @Skarlso - fix: only wait for changeset if the result is not empty
- PR #4285 - @matheuscscp - Add badge for SLSA Level 3
- PR #4284 - @errordeveloper - Make
flux pull
work for OCI artifacts produced by other tools - PR #4270 - @Azhovan - feat: add bootstrap gitea command
- PR #4255 - @hiddeco - tests/azure: update controller dependencies
- PR #4251 - @fluxcdbot - Update toolkit components
- PR #4238 - @makkes - Upgrade github.com/fluxcd/pkg/{git,git/gogit}
- PR #4233 - @sonbui00 - chore: remove support armv6h for aur package
- PR #4228 - @sonbui00 - Improve AUR package templates
- PR #4226 - @somtochiama - Update descriptio...
v2.1.2
Highlights
Flux v2.1.2
is a patch release which comes with various fixes. Users are encouraged to upgrade for the best experience.
Fixes
- Ensures faster recovery of
Kustomization
andHelmRelease
resources when the source-controller has restarted and is working on restoring the storage. - Prevent source-controller from failing to reconcile
OCIRepositories
when artifacts contain symlinks. - Addresses issue with helm-controller miss-labeling Custom Resource Definitions.
- Detect immutable field errors in Google Cloud resources managed by Flux
Kustomizations
. - Better error reporting for
flux bootstrap
when the owner doesn't match the identity associated with the given token. - Allow
flux pull artifact
to fetch OCI artifacts produced by other tools.
Components changelog
CLI Changelog
- PR #4324 - @somtochiama - bootstrap: Fix error msg when the Git token doesn't match the repo owner
- PR #4323 - @stefanprodan - e2e: Update Go dependencies
- PR #4313 - @fluxcdbot - Update toolkit components
- PR #4296 - @Skarlso - fix: only wait for changeset if the result is not empty
- PR #4285 - @matheuscscp - Add badge for SLSA Level 3
- PR #4284 - @errordeveloper - Make
flux pull
work for OCI artifacts produced by other tools
v2.1.1
Highlights
Flux v2.1.1
is a patch release which comes with various fixes. Users are encouraged to upgrade for the best experience.
Fixes
- Use auto lookup strategy for Buckets to widen support for S3-compatible object storage services (
source-controller
). - Fix Secret type check for HelmRepositories TLS certs referred in
.spec.secretRef
(source-controller
). - Fix the branch name reporting when the push branch is the same as the checkout branch (
image-automation-controller
). - Restore Helm logs inclusion in failure events (
helm-controller
). - Fix the impersonation of the default service account when diffing HelmReleases (
helm-controller
). - Check source for
nil
artifact before loading Helm charts (helm-controller
). - Update the description of Kubernetes specific flag to distinguish them from Flux bootstrap flags (
flux
CLI).
Components changelog
CLI Changelog
- PR #4255 - @hiddeco - tests/azure: update controller dependencies
- PR #4251 - @fluxcdbot - Update toolkit components
- PR #4246 - @dependabot[bot] - build(deps): bump the ci group with 4 updates
- PR #4238 - @makkes - Upgrade github.com/fluxcd/pkg/{git,git/gogit}
- PR #4233 - @sonbui00 - chore: remove support armv6h for aur package
- PR #4228 - @sonbui00 - Improve AUR package templates
- PR #4227 - @dependabot[bot] - build(deps): bump the ci group with 3 updates
- PR #4226 - @somtochiama - Update description of kubeconfig specific flag
- PR #4222 - @dependabot[bot] - build(deps): bump github.com/cyphar/filepath-securejoin from 0.2.3 to 0.2.4 in /tests/integration
- PR #4221 - @dependabot[bot] - build(deps): bump github.com/cyphar/filepath-securejoin from 0.2.3 to 0.2.4 in /tests/azure
- PR #4215 - @dependabot[bot] - build(deps): bump the ci group with 4 updates
- PR #4213 - @dependabot[bot] - build(deps): bump github.com/docker/distribution from 2.8.1+incompatible to 2.8.2+incompatible in /tests/integration
- PR #4212 - @dependabot[bot] - build(deps): bump github.com/docker/docker from 23.0.1+incompatible to 23.0.3+incompatible in /tests/integration
- PR #4198 - @makkes - Add 2.1.x backport label
- PR #4197 - @stefanprodan - Fix links to fluxcd.io
- PR #4195 - @dependabot[bot] - build(deps): bump the ci group with 2 updates
v2.1.0
Highlights
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.
❤️ Big thanks to all the Flux contributors that helped us with this release!
Deprecations
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.
API changes
GitRepository v1
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 valuesHEAD
,Tag
,TagAndHEAD
.
Kustomization v1
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.
ImageUpdateAutomation v1beta1
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.
Kubernetes TLS Secrets
All the Flux APIs that accept TLS data have been modified to adopt Secrets of type
kubernetes.io/tls
. This includes:
- HelmRepository: The field
.spec.secretRef
has been deprecated in favor of a new field.spec.certSecretRef
. - OCIRepository: Support for the
caFile
,keyFile
andcertFile
keys in the Secret specified in.spec.certSecretRef
have been deprecated in favor ofca.crt
,tls.key
andtls.crt
. - ImageRepository: Support for the
caFile
,keyFile
andcertFile
keys in the Secret specified in.spec.certSecretRef
have been deprecated in favor ofca.crt
,tls.key
andtls.crt
. - GitRepository: CA certificate can now be provided in the Secret specified in
.spec.secretRef
using theca.crt
key, which takes precedence over thecaFile
key.
Upgrade procedure
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.
Kubernetes compatibility
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.
New Documentation
- Flux installation
- Flux bootstrap
- Flux configuration
- Flux Prometheus metrics
- Flux custom Prometheus metrics
- Flux logs
- Flux events
Components changelog
- source-controller v1.1.0
- kustomize-controller v1.1.0
- notification-controller v1.1.0
- helm-controller v0.36.0
- image-reflector-controller v0.30.0
- image-automation-controller v0.36.0
CLI Changelog
- PR #4189 - @hiddeco - Update dependencies
- PR #4186 - @fluxcdbot - Update toolkit components
- PR #4183 - @somtochiama - Fix autocompletion for helm chart
- PR #4182 - @hiddeco - manifestgen/install: use clean default HTTP client
- PR #4181 - @hiddeco - cmd/events: handle error value
- PR #4180 - @stefanprodan - Fix controller version info
- PR #4177 - @stefanprodan - Set min value for the
--ssh-rsa-bits
flag - PR #4176 - @hiddeco - ci: disable fail-fast for ARM end-to-end
- PR #4175 - @hiddeco - build: update securejoin dependency
- PR #4169 - @darkowlzz - Add monitoring configuration deprecation notice
- PR #4167 - @dependabot[bot] - build(deps): bump the ci group with 2 updates
- PR #4166 - @stefanprodan - e2e: Add Kubernetes v1.28.0 to conformance tests
- PR #4151 - @hiddeco - ci: enable security-and-quality CodeQL query
- PR #4147 - @aryan9600 - Adopt Kubernetes style TLS Secrets and add relevant flags
- PR #4142 - @dependabot[bot] - build(deps): bump the ci group with 2 updates
- PR #4140 - @somtochiama - Disable azure e2e test
- PR #4134 - @sestegra - monitoring: add OCIRepository in cluster dashboard and new source panels in control-plane dashboard
- PR #4131 - @mraerino - Fix selection of kustomization resource from multi doc yaml
- PR #4126 - @stefanprodan - Set Kubernetes min version to 1.25
- PR #4077 - @dependabot[bot] - build(deps): bump the ci group with 2 updates
- PR #4068 - @stefanprodan - Update dependencies
- PR #4065 - @hiddeco - action: support
openssl
andsha256sum
- PR #4062 - @souleb - diff: Take into account the server-side inventory for local Flux Kustomizations
- PR #4061 - @hiddeco - action: re-allow configuration of non-default token
- PR #4057 - @fluxcdbot - Update toolkit components
- PR #4052 - @stefanprodan - docs: Link to the Flux GitHub Action documentation
- PR #4051 - @hiddeco - action: use
$RUNNER_TOOL_CACHE
, support MacOS and Windows, validate checksum - PR #4046 - @stefanprodan - ci: backport: set write permissions
- PR #4043 - @stefanprodan - ci: release: extract the image tag from GITHUB_REF
- PR #4041 - @hiddeco - ci: release: disable interpretation backslash esc
v2.0.1
Highlights
Flux v2.0.1
is a patch release which comes with various fixes. Users are encouraged to upgrade for the best experience.
💡 For upgrading from Flux v0.x
, please see the procedure documented in 2.0.0.
Fixes
- Fix AWS auth for cross-region ECR repositories (
source-controller
,image-reflector-controller
). - Prevent spurious alerts for skipped resources (
kustomize-controller
). - List removed resources for
flux diff ks --kustomization-file
(flux
CLI). - Fix SLSA provenance generation for the Flux CLI binaries.
Components changelog
CLI Changelog
- PR #4068 - @stefanprodan - Update dependencies
- PR #4065 - @hiddeco - action: support
openssl
andsha256sum
- PR #4062 - @souleb - diff: Take into account the server-side inventory for local Flux Kustomizations
- PR #4061 - @hiddeco - action: re-allow configuration of non-default token
- PR #4057 - @fluxcdbot - Update toolkit components
- PR #4052 - @stefanprodan - docs: Link to the Flux GitHub Action documentation
- PR #4051 - @hiddeco - action: use
$RUNNER_TOOL_CACHE
, support MacOS and Windows, validate checksum - PR #4046 - @stefanprodan - ci: backport: set write permissions
- PR #4043 - @stefanprodan - ci: release: extract the image tag from GITHUB_REF
- PR #4041 - @hiddeco - ci: release: disable interpretation backslash esc
New Documentation
v2.0.0
Highlights
This 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.
Supported versions
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.
Kubernetes compatibility
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.
Flux ecosystem support
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 |
API changes
GitRepository v1
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:
- the deprecated field
.spec.gitImplementation
was removed - the unused field
.spec.accessFrom
was removed - the deprecated field
.status.contentConfigChecksum
was removed - the deprecated field
.status.artifact.checksum
was removed - the
.status.url
was removed (replaced by.status.artifact.url
)
Kustomization v1
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:
- the deprecated field
.spec.validation
was removed - the deprecated field
.spec.patchesStrategicMerge
was removed (replaced by.spec.patches
) - the deprecated field
.spec.patchesJson6902
was removed (replaced by.spec.patches
)
Receiver v1
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:
- the deprecated field
.status.url
was removed (replaced by.status.webhookPath
)
Upgrade procedure
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:
- Remove the deprecated fields from the
GitRepository
andKustomization
definitions. - Commit, push and reconcile the fields removal changes.
- Set
apiVersion: source.toolkit.fluxcd.io/v1
in the YAML files that containGitRepository
definitions. - Set
apiVersion: kustomize.toolkit.fluxcd.io/v1
in the YAML files that contain FluxKustomization
definitions. - Set
apiVersion: notification.toolkit.fluxcd.io/v1
in the YAML files that containReceiver
definitions. - Update the API version of
GitRepository
andKustomization
objects present in the.spec.resources
list ofReceiver
definitions. - Commit, push and reconcile the API version changes.
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.
New Documentation
- Release cadence and support
- SLSA Assessment
- Controller sharding and horizontal scaling
- GitRepository v1 specification
- Kustomization v1 specification
- Receiver v1 specification
❤️ Big thanks to all the Flux contributors that helped us reach this milestone!
👏 And a special shoutout to the Flux community who supported us over the years!
Components changelog
- source-controller v1.0.0
- kustomize-controller v1.0.0
- notification-controller v1.0.0
- helm-controller v0.35.0
- image-reflector-controller v0.29.0
- image-automation-controller v0.35.0
CLI Changelog
- PR #4035 - @stefanprodan - Update dependencies
- PR #4033 - @stefanprodan - docs: link to releases spec from website
- PR #4031 - @stefanprodan - Run conformance tests for Kubernetes v1.27.3
- PR #4029 - @stefanprodan - Run e2e tests on release branches
- PR #4028 - @makkes - Annotate errors from go-git-providers
- PR #4027 - @hiddeco - Update go-git to unreleased v5.8.0
- PR #4023 - @stefanprodan - Add backport GitHub Action workflow
- PR #4020 - @stefanprodan - Set minimum supported version to Kubernetes 1.24.0
- PR #4018 - @stefanprodan - docs: Fix the
flux push
example for ECR - PR #4015 - @stefanprodan - Align
go.mod
version with Kubernetes (Go 1.20) - PR #4008 - @stefanprodan - Add SLSA3 generators to release workflow
- PR #4006 - @fluxcdbot - Update toolkit components
- PR #4002 - @makkes - Don't log errors with missing CRDs for "get * all" commands
- PR #3990 - @aryan9600 - RFC-0004: add section about proxy
- PR #3976 - @darklore - Use equivalent and shorter way to generate shell completions
- PR #3955 - @somtochiama - Fix 'patchesJson6902' is deprecated' warning
- PR #3945 - @makkes - Make
flux logs
more lenient