FluxCD v2 - 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.

:heart: 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:

1. Set apiVersion: helm.toolkit.fluxcd.io/v2beta2 in the YAML files that contain HelmRelease definitions.
2. Set apiVersion: notification.toolkit.fluxcd.io/v1beta3 in the YAML files that contain Alert and Provider definitions.
3. 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

• HelmRelease v2beta2 specification
• Enable in-memory kustomize builds guide

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 description of kubeconfig specific flag
• PR #4198 - @makkes - Add 2.1.x backport label
• PR #4197 - @stefanprodan - Fix links to fluxcd.io