Announcing Flux 2.5 GA

We are thrilled to announce the release of Flux v2.5.0! Here you will find highlights of new features and improvements in this release.
By Stefan Prodan |
Tags:

We are thrilled to announce the release of Flux v2.5.0! In this post, we will highlight some of the new features and improvements included in this release.

Highlights

Flux v2.5 marks a significant milestone in the project’s evolution, we have integrated Common Expression Language (CEL) with the Flux controllers to enable long-awaited features such as custom health checks and webhook receiver filters. Moreover, we have added support for GitHub App authentication, custom event metadata for notifications and Flux CLI helpers for troubleshooting Flux resources.

In ecosystem news, the Flux Operator v0.14 release brings one of the most requested features: deploy app code and/or config changes made in a GitHub Pull Request or GitLab Merge Request to an ephemeral environment for testing and validation.

The Flux Operator has the ability to create, update and delete application instances on-demand based on the ResourceSet definitions and Pull/Merge Requests state.

For more details on how to use the ephemeral environments feature, see the following guides:

Health Checks for Custom Resources

In this release, we have extended the Flux Kustomization API with support for defining custom health checks using Common Expression Language (CEL). The health checks are used to verify the readiness of the resources managed by Flux and are a key feature for ensuring that the desired state of the cluster is achieved.

While Flux performs a series of built-in health checks for Kubernetes core resources, the new feature allows users to teach Flux how to check the health of Kubernetes custom resources. This is particularly useful for custom resources that do not subscribe to the Kubernetes API conventions or for resources that require additional logic to determine if they reached the desired state.

A common use case for custom health checks is to verify the status of Cluster objects reconciled by the Cluster API controllers. When Flux is used to manage a fleet of Kubernetes clusters, the health checks can be used to ensure that the clusters are ready before deploying cluster addons and applications.

Example of a Kustomization with a custom health check for Cluster API:

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: prod-clusters
  namespace: infra
spec:
  interval: 30m
  retryInterval: 5m
  prune: true
  sourceRef:
    kind: GitRepository
    name: fleet
  path: "./production"
  timeout: 15m
  wait: true
  healthCheckExprs:
    - apiVersion: cluster.x-k8s.io/v1beta1
      kind: Cluster
      failed: "status.conditions.filter(e, e.type == 'Ready').all(e, e.status == 'False')"
      current: "status.conditions.filter(e, e.type == 'Ready').all(e, e.status == 'True')"

The above example configures Flux to wait for all the Cluster objects to reach the Ready state before proceeding with the reconciliation of other Kustomizations that have a dependsOn relationship defined for the prod-clusters.

We have published a health check library that contains CEL expressions for popular custom resources. The library is community-maintained, and we encourage users to contribute new health checks.

Other kustomize-controller improvements include:

  • Fine-grained control of garbage collection with .spec.deletionPolicy.
  • SOPS support for decryption of Kubernetes secrets generated by Kustomize components.

GitHub App Authentication for Git Repositories

Starting with Flux v2.5, you can configure source-controller and image-automation-controller to authenticate against GitHub repositories using a GitHub App installation.

Instead of relying on personal access tokens or SSH keys that require manual rotation, you can now configure Flux to authenticate against GitHub repositories using an identity that is not tied to a specific user account.

We have added a new command to the Flux CLI that can be used to create the Kubernetes Secret required for the GitHub App authentication.

flux create secret githubapp github-auth \
  --app-id=1 \
  --app-installation-id=2 \
  --app-private-key=~/private-key.pem

The Kubernetes Secret generated by the above command can be referenced in a GitRepository and ImageUpdateAutomation with .spec.secretRef.name.

For more details on how to configure the GitHub App authentication, see the GitRepository API documentation.

Custom event metadata for notifications

Starting with Flux v2.5, users can enrich the metadata of the events sent by the notification-controller by adding annotations on the Flux Kustomization and HelmRelease resources. The metadata is included in the notifications sent to the configured providers, such as Slack, Microsoft Teams, etc., and can be used to provide additional context about a particular application or environment.

One highly requested feature was the ability to include the image tag in the notifications send when Flux image automation updates the container image tag in HelmRelease values.

Example of a HelmRelease with custom event metadata containing the image tag:

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: my-app
  namespace: apps
  annotations:
    event.toolkit.fluxcd.io/image: docker.io/org/my-app:1.0.0 # {"$imagepolicy": "apps:my-app"}
spec:
  chart:
    spec:
      chart: my-app
      sourceRef:
        kind: HelmRepository
        name: podinfo
  values:
    image:
      tag: 1.0.0  # {"$imagepolicy": "apps:my-app:tag"}

When the image automation updates the my-app HelmRelease with a new image tag e.g. 1.0.1, the notification sent after the Helm release upgrade will include image: docker.io/org/my-app:1.0.1 in message body.

For more details on how to configure custom event metadata, see the Alert API documentation.

Other notifications improvements include:

  • The notification-controller is now capable of updating Git commit statuses from events about Kustomizations that consume OCIRepositories.
  • The Receiver API now supports filtering the declared resources that match a given Common Expression Language (CEL) expression.

CLI Improvements

To help users troubleshoot Flux, we’ve added a new flux debug command the following subcommands:

  • flux debug kustomization --show-vars used to inspect the final variables values by merging the Flux Kustomization inline vars with the vars coming from Kubernetes ConfigMaps/Secrets.
  • flux debug helmrelease --show-values used to inspect the final Helm values by merging the HelmRelease inline values with the values coming from Kubernetes ConfigMaps/Secrets.

Note that these commands will print sensitive information if Kubernetes Secrets are referenced in the Flux Kustomization or HelmRelease resources.

Other CLI improvements include:

  • A new command was added, flux create secret githubapp that can be used to generate a Kubernetes Secret for GitHub App authentication.
  • The flux create source git command now supports the --provider=github flag to configure GitHub App authentication for Git repositories.

Supported Versions

Flux v2.2 has reached end-of-life and is no longer supported.

Flux v2.5 supports the following Kubernetes versions:

DistributionVersions
Kubernetes1.30, 1.31, 1.32
OpenShift4.17

Over and out

If you have any questions, or simply just like what you read and want to get involved, here are a few good ways to reach us: