---
author: Stefan Prodan
date: 2025-02-20 12:00:00+00:00
title: Announcing Flux 2.5 GA
description: "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."
url: /blog/2025/02/flux-v2.5.0/
tags: [announcement]
resources:
- src: "**.{png,jpg}"
  title: "Image #:counter"
---

We are thrilled to announce the release of [Flux v2.5.0](https://github.com/fluxcd/flux2/releases/tag/v2.5.0)!
In this post, we will highlight some of the new features and improvements included in this release.

![](featured-image.png)

## 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](https://github.com/controlplaneio-fluxcd/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](https://fluxcd.control-plane.io/operator/resourcesets/introduction/)
definitions and Pull/Merge Requests state.

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

- [Ephemeral Environments for GitHub Pull Requests](https://fluxcd.control-plane.io/operator/resourcesets/github-pull-requests/)
- [Ephemeral Environments for GitLab Merge Requests](https://fluxcd.control-plane.io/operator/resourcesets/gitlab-merge-requests/)

### Health Checks for Custom Resources

In this release, we have extended the Flux [Kustomization](/flux/components/kustomize/kustomizations/) 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](https://cluster-api.sigs.k8s.io/) 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:

```yaml
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](/flux/components/kustomize/kustomizations/#dependencies) relationship
defined for the `prod-clusters`.

We have published a [health check library](/flux/cheatsheets/cel-healthchecks/) 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](https://fluxcd.io/flux/components/kustomize/kustomizations/#deletion-policy).
- 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.

```shell
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](https://fluxcd.io/flux/components/source/gitrepositories/#github).

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

```yaml
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](https://fluxcd.io/flux/components/notification/alerts/#event-metadata-from-object-annotations).

Other notifications improvements include:

- The notification-controller is now capable of updating
  [Git commit statuses](https://fluxcd.io/flux/cheatsheets/oci-artifacts/#git-commit-status-updates)
  from events about Kustomizations that consume OCIRepositories.
- The [Receiver API](https://fluxcd.io/flux/components/notification/receivers/#filtering-reconciled-objects-with-cel)
  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:

| Distribution | Versions         |
|:-------------|:-----------------|
| Kubernetes   | 1.30, 1.31, 1.32 |
| OpenShift    | 4.17             |

{{% alert color="info" title="Enterprise support" %}}
Note that the CNCF 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](https://control-plane.io/enterprise-for-flux-cd/) that provide
enterprise support for Flux.
{{% /alert %}}

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

- Join our [upcoming dev meetings](https://fluxcd.io/community/#meetings).
- Join the [Flux mailing list](https://lists.cncf.io/g/cncf-flux-dev) and let us know what you need help with.
- Talk to us in the #flux channel on [CNCF Slack](https://slack.cncf.io/).
- Join the [planning discussions](https://github.com/fluxcd/flux2/discussions).
- Follow [Flux on Twitter](https://twitter.com/fluxcd), or join the
  [Flux LinkedIn group](https://www.linkedin.com/groups/8985374/).
