Flux – Flux releases

Flux: Flux controller releases

Mon, 01 Jan 0001 00:00:00 +0000

The Flux controllers are Kubernetes operators, each controller has its own Git repository and release cycle (see below for details).

Controller repositories and their interdependencies:

source-controller
kustomize-controller (imports fluxcd/source-controller/api)
helm-controller (imports fluxcd/source-controller/api)
notification-controller
image-reflector-controller
image-automation-controller (imports fluxcd/source-controller/api and fluxcd/image-reflector-controller/api)

API versioning

The Flux APIs (Kubernetes CRDs) follow the Kubernetes API versioning scheme.

Alpha version

An alpha version API e.g. v1alpha1 is considered experimental and should be used on test environments only.

The schema of objects may change in incompatible ways in a later API version. The Custom Resources may require editing and re-creating after a CRD update.

An alpha version API becomes deprecated once a subsequent alpha or beta API version is released. A deprecated alpha version is subject to removal after a three month period.

An alpha API is introduced when its proposal reaches the implementable phase in the Flux RFC process. We encourage users to try out the alpha APIs and provide feedback (e.g. on CNCF Slack or in the form of GitHub issues/discussions) which is extremely valuable during early stages of development.

Beta version

A beta version API e.g. v2beta1 is considered well-tested and safe to use in production.

The schema of objects may change in incompatible ways in a subsequent beta or stable API version. The Custom Resources may require editing after a CRD update for which migration instructions will be provided as part of the controller changelog.

A beta version API becomes deprecated once a subsequent beta or stable API version is released. A deprecated beta version is subject to removal after a six-months period.

Stable version

A stable API version, e.g. v2, is considered feature complete.

Any changes to the object schema do not require editing or re-creating of Custom Resources. Schema fields can’t be removed, only new fields can be added with a default value that doesn’t affect the controller’s current behaviour.

A stable API version becomes deprecated once a subsequent stable version is released. Stable API versions are not subject to removal in any future release within a controller major version.

In effect, this means that for as long as Flux v2 is being maintained, all the stable API versions will be supported.

Controller versioning

The Flux controllers and their Go API packages are released by following the Go module version numbering conventions:

vX.Y.Z-rc.W release candidates e.g. v1.0.0-rc.1
vX.Y.Z stable releases e.g. v1.0.0

The Flux project maintains release branches for the most recent three minor releases of each controller e.g. release/v1.0.x, release/v1.1.x and release/v1.2.x.

The API versioning and controller versioning are indirectly related. For example, a source-controller minor release v1.1.0 can introduce a new API version v1beta1 for a Kind XRepository in the source.toolkit.fluxcd.io group.

Release candidates

Release candidates are intended for testing new features or improvements before a final release.

In most cases, a maintainer will publish a release candidate of a controller for Flux users to tests it on their staging clusters. Release candidates are not meant to be deployed in production unless advised to do so by a maintainer.

Patch releases

Patch releases are intended for critical bug fixes to the latest minor version, such as addressing security vulnerabilities or fixes to severe problems with no workaround.

Patch releases do not contain breaking changes, feature additions or any type of user-facing changes. If a security fix requires a breaking change, then a minor release will provide the fix.

We expect users to be running the latest patch release of a given minor release as soon as the controller release is included in a Flux patch release.

Minor releases

Minor releases are intended for backwards compatible feature additions and improvements. Note that breaking changes may occur if required by a security vulnerability fix.

In addition, minor releases are used when updating Kubernetes dependencies such as k8s.io/api from one minor version to another.

In effect, this means a controller minor version will be released at least every four months, after each Kubernetes minor version release. For in-depth information about this, please refer to the release cadence section of this document.

Major releases

Major releases are intended for drastic changes in the controller behaviour or security stance.

A controller major release will be announced ahead of time throughout all communication channels, and a support window of one year will be provided for the previous major version.

Release cadence

Flux controllers are at least released at the same rate as Kubernetes, following their cadence of three minor releases per year.

To properly validate the controllers against the latest Kubernetes version, we typically allocate a time window of around two weeks for end-to-end testing of Flux controllers. The newly released controllers offer support for Kubernetes N-2 minor versions.

It is worth noting that in certain scenarios where project dependencies are not in sync with the Kubernetes version or conflicts arise, this two-week timeframe may prove insufficient, requiring additional time to address the issues appropriately.

A Flux controller may have more than three minor releases per year, if maintainers decide to ship a new feature or optimisation ahead of schedule.

Supported releases

For Flux controllers we support the last three minor releases.

Security fixes may be back-ported to those three minor versions as patch releases, depending on severity and feasibility.

Note that back-porting is provided by the community on a best-effort basis.

Release artifacts

Each controller release produces the following artifacts:

Source code (GitHub Releases page)
Software Bill of Materials in SPDX format (GitHub Releases page)
SLSA provenance attestations (GitHub Releases page)
Kubernetes manifests such as CRDs and Deployments (GitHub Releases page)
Signed checksums of source code, SBOM and manifests (GitHub Releases page)
Multi-arch container images (GitHub Container Registry and DockerHub)

All the artifacts are cryptographically signed and can be verified with Cosign and GitHub OIDC.

The release artifacts can be accessed based on the controller name and version.

Flux: Flux shared packages releases

Mon, 01 Jan 0001 00:00:00 +0000

The Go packages in github.com/fluxcd/pkg are dedicated Go modules, each module has its own set of dependencies and release cycle.

These packages are primarily meant for internal use in Flux controllers and for projects which integrate and/or extend Flux.

Release versioning

The Flux packages are released by following the Go module version numbering conventions:

NAME/vX.Y.Z-rc.W release candidates e.g. runtime/v1.0.0-rc.1
NAME/vX.Y.Z stable releases e.g. runtime/v1.0.0

To import or update a Flux package in a Go project:

go get github.com/fluxcd/pkg/runtime@v1.0.0

Release candidates

Release candidates are intended for testing new features or improvements.

In most cases, a maintainer will cut a release candidate of a package to include it in a Flux controller release candidate.

Release candidates are not meant to be included in Flux stable releases. Before cutting a stable release of a controller, all imported Flux packages must be pinned to a stable version.

Patch releases

Patch releases are intended for critical bug fixes to the latest minor version, such as addressing security vulnerabilities or fixes to severe problems with no workaround.

Patch releases should not contain breaking changes, feature additions or any type of improvements.

Patch releases should be used when updating dependencies such as k8s.io/api from one patch version to another.

Minor releases

Minor releases are intended for backwards compatible feature additions and improvements.

Minor releases should be used when updating dependencies such as k8s.io/api from one minor version to another. If a Kubernetes minor version upgrade requires a breaking change (e.g. removal of an API such as PodSecurityPolicy) in a Flux package public API, then a major version release is necessary.

Major releases

Major releases are intended for backwards incompatible feature additions and improvements.

Any change to a package public API, such as a change to a Go function signature, requires a new major release.

Supported releases

For Flux Go packages we only support the latest stable release. We expect for projects that depend on Flux packages to stay up-to-date by automating the Go modules updates with tools like Dependabot.

In effect, this means we’ll not backport CVE fixes to an older minor or major version of a package.

Deprecation policy

A Flux Go package can be deprecated at any time. Usually a deprecated package may be replaced a different one, but there are no guarantees to always have a suitable replacement.

A deprecated package is marked as so in its go.mod e.g.

// Deprecated: use github.com/fluxcd/pkg/tar instead.
module github.com/fluxcd/pkg/untar

Flux: Flux release procedures

Mon, 01 Jan 0001 00:00:00 +0000

This document provides an overview of the release procedures for each component type in the Flux project. It is intended for project maintainers, but may also be useful for contributors who want to understand the release process.

If you have any questions, please reach out to another maintainer for clarification.

General rules
- Signing releases
Component types
Backport changes for patch releases
- Manual backporting

General rules

Signing releases

To ensure the integrity and authenticity of releases, all releases must be signed with a GPG key. The public key must be uploaded to the GitHub account of the maintainer, and the private key must be kept secure.

In addition, we recommend the following practices:

Safeguard your GPG private key, preferably using a hardware security key like a YubiKey.
Use a subkey dedicated to signing releases, set an expiration date for added security, and keep the master key offline. Refer to this guide for detailed instructions.

We understand that this may seem overwhelming. If you are not comfortable with the process, don’t hesitate to seek assistance from another maintainer who has experience with signing releases.

Please note that SSH signatures are not supported at this time due to limited availability of SSH signature verification outside the git CLI.

Component types

Shared packages

To release a package as a project maintainer, follow these steps:

Tag the main branch using SemVer.
Sign the tag according to the general rules.
Push the signed tag to the upstream repository.

Use the following commands as an example:

git clone https://github.com/fluxcd/pkg.git
git switch main
git tag -s -m "<module>/<semver>" "<module>/<semver>"
git push origin "<module>/<semver>"

In the commands above, <module> represents the relative path to the directory containing the go.mod file, and <semver> refers to the SemVer version of the release. For instance, runtime/v1.0.0 for fluxcd/pkg/runtime, or http/fetch/v0.1.0 for fluxcd/pkg/http/fetch.

Before cutting a release candidate, ensure that the package’s tests pass successfully.

Here’s an example of releasing a candidate from a feature branch:

git switch <feature-branch>
git tag -s -m "<module>/<semver>-<feature>.1" "<module>/<semver>-<feature>.1"
git push origin "<module>/<semver>-<feature>.1"

Controllers

To release a controller as a project maintainer, follow the steps below. Note that the release procedure differs depending on the type of release.

Controllers: minor releases

Checkout the main branch and pull changes from the remote repository.
Create a “release series” branch for the next minor SemVer range, e.g., release/v1.2.x, and push it to the remote repository.
```
git switch -c release/v1.2.x main
git push origin release/v1.2.x
```
From the release series branch, create a release preparation branch for the specific release.
```
git switch -c release-v1.2.0 release/v1.2.x
```

Add an entry to CHANGELOG.md for the new release and commit the changes.

vim CHANGELOG.md
git add CHANGELOG.md
git commit -s -m "Add changelog entry for v1.2.0"

Update github.com/fluxcd/<name>-controller/api version in go.mod and newTag value in config/manager/kustomization.yaml to the target SemVer (e.g., v1.2.0). Commit and push the changes.
```
vim go.mod
vim config/manager/kustomization.yaml
git add go.mod config/manager/kustomization.yaml
git commit -s -m "Release v1.2.0"
git push origin release-v1.2.0
```
Create a pull request for the release branch and merge it into the release series branch (e.g., release/v1.2.x).

Create api/<next semver> and <next semver> tags for the merge commit in release/v1.2.x. Ensure the tags are signed according to the general rules, and push them to the remote repository.

git switch release/v1.2.x
git pull origin release/v1.2.x
git tag -s -m "api/v1.2.0" api/v1.2.0
git push origin api/v1.2.0
git tag -s -m "v1.2.0" v1.2.0
git push origin v1.2.0

Confirm that the CI builds and releases the newly tagged version.
Create a pull request for the release series branch and merge it into main.
Add the backport/v1.2.x label to .github/labels.yaml and create a pull request against main.

Controllers: patch releases

Ensure everything to be included in the release is backported to the “release series” branch (e.g., release/v1.2.x). If not, refer to the backporting section.

From the release series branch, create a release preparation branch for the specific patch release.

git switch release/v1.2.x
git pull origin release/v1.2.x
git switch -c release-v1.2.1 release/v1.2.x

Add an entry to CHANGELOG.md for the new release and commit the changes.

vim CHANGELOG.md
git add CHANGELOG.md
git commit -s -m "Add changelog entry for v1.2.1"

Update github.com/fluxcd/<name>-controller/api version in go.mod and newTag value in config/manager/kustomization.yaml to the target SemVer (e.g., v1.2.1). Commit and push the changes.
```
vim go.mod
vim config/manager/kustomization.yaml
git add go.mod config/manager/kustomization.yaml
git commit -s -m "Release v1.2.1"
git push origin release-v1.2.1
```
Create a pull request for the release branch and merge it into the release series branch (e.g., release/v1.2.x).

Create api/<next semver> and <next semver> tags for the merge commit in release/v1.2.x. Ensure the tags are signed according to the general rules, and push them to the remote repository.

git switch release/v1.2.x
git pull origin release/v1.2.x
git tag -s -m "api/v1.2.1" api/v1.2.1
git push origin api/v1.2.1
git tag -s -m "v1.2.1" v1.2.1
git push origin v1.2.1

Confirm that the CI builds and releases the newly tagged version.

Cherry-pick the changelog entry from the release series branch and create a pull request to merge it into main.

git switch main
git pull origin main
git switch -c pick-changelog-v1.2.1 main
git cherry-pick -x <commit hash>
git push origin pick-changelog-v1.2.1

Controllers: release candidates

In some cases, it may be necessary to release a release candidate of a controller.

To create a first release candidate, follow the steps to create a minor release, but use the rc.X suffix for SemVer version to release (e.g., v1.2.0-rc.1).

Once the release series branch is created, subsequent release candidates and the final (non-RC) release should follow the procedure for patch controller releases.

Controllers: preview releases

In some cases, it may be necessary to release a preview of a controller. A preview release is a release that is not intended for production use, but rather to allow users to quickly test new features or an intended bug fix, and provide feedback.

Preview releases are made by triggering the release GitHub Actions workflow on a specific Git branch. This workflow will build the container image, sign it using Cosign, and push it to the registry. But it does not require a Git tag, GitHub release, or a changelog entry.

To create a preview release, follow the steps below.

Navigate to https://github.com/fluxcd/<name>-controller/actions/workflows/release.yml.
Click the Run workflow button.
Select the branch to release from the Branch dropdown.
The default values for the image tag (preview) should be correct, but can be changed if necessary.
Click the green Run workflow button.
The workflow will now run, and the container image will be pushed to the registry. Once the workflow has completed, the image reference will be available in the logs, and can be shared in the relevant issue or pull request.

Distribution

To release a Flux distribution as a project maintainer, follow the steps below.

Note that the Flux distribution contains multiple components, and you may need to release controllers before releasing the distribution. Automation is in place to automatically create a pull request to update the version in the main branch when a new controller version is released.

Distribution: minor releases

Ensure everything to be included in the release is merged into the main branch, including any controller releases you wish to include in the release.
Create a “release series” branch for the next minor SemVer range, e.g., release/v2.2.x, and push it to the remote repository.
```
git switch -c release/v2.2.x main
```
Prepare the required release notes for this release, see release notes for more information.
Tag the release series branch with the SemVer version of the release, e.g., v1.2.0. Ensure the tag is signed according to the general rules, and push it to the remote repository.
```
git tag -s -m "v2.2.0" v2.2.0
git push origin v2.2.0
```
Confirm that the CI builds and releases the newly tagged version.
Once the release is complete, update the release notes on GitHub with the release notes prepared in step 3.
Post a message in the #flux CNCF Slack channel announcing the release, and pin it.
Add the backport/v2.2.x label to .github/labels.yaml and create a pull request against main.

Distribution: minor release website

The website at fluxcd.io always reflects the latest Flux minor version. Each Flux minor release is reflected by a respective branch in the website repo, i.e. for Flux 2.3, the website is deployed from the branch v2-3. The website’s main branch reflects the next Flux minor release and is used for development. The website for that branch is hosted at https://main.docs.fluxcd.io. For older Flux versions, the website is hosted at https://v2-MINOR.docs.fluxcd.io/.

The following instructions assume you’re updating the website for the Flux release v2.N:

Check out the main branch in the website repo and apply the following changes to the hugo.yaml file:
1. Add the following entry to params.versions:
```
- version: "v2.N"
 url: https://fluxcd.io
```
2. Edit the existing params.versions entry pointing to https://fluxcd.io to point to https://v2-(N-1).docs.fluxcd.io
3. Remove the oldest entry from params.versions. We only support N-2 releases.
4. Do not set params.version - this string is used by the other branches only, and setting it here will likely cause automatic backports to fail with a conflict.
In .github/labels.yaml add an entry for the backport:v2-N label by copying the existing backport:v2-(N-1) one.
Commit the changes and create a PR for the main branch.

As soon as the PR is merged, create the “v2-N” branch from main:

git checkout main
git pull
git checkout -b v2-N
git push origin HEAD:v2-N

Apply the labels backport:v2-(N-1) and backport:v2-(N-2) to the PR created above so that the hugo.yaml file gets updated in the older versions’ websites. This step will lead to 2 PRs being automatically created for the two last supported release branches of the website. Do not merge these PRs, yet!
In the PR for the v2-(N-1) branch, edit the hugo.yaml file and set params.archived_version to true.
Go to https://app.netlify.com/sites/fluxcd/configuration/deploys#branches-and-deploy-contexts
Click on “Configure”
In “Production branch”, change the value from v2-(N-1) to v2-N.
In “Additional branches” add the “v2-(N-1)” branch.
Click “Save”.
Now merge the 2 PRs created by the labels you applied in the previous step.
Create another PR against the main branch to:
1. Update the trigger_branch URL query parameter in the file .github/workflows/netlify.yml to point to “v2-N”.
2. Update the website announcement banner in the file content/en/_index.html to point to the blog post of the new release, and change the string right below from Announcing Flux 2.N-1 GA to Announcing Flux 2.N GA.
Merge the PR and backport to the v2-N branch by applying the backport:v2-N label to the PR.
1. In the backport PR, set the params.version string to the version 2.N.

Distribution: patch releases

Ensure everything to be included in the release is backported to the “release series” branch (e.g., release/v2.2.x). If not, refer to the backporting section.
Prepare the required release notes for this release, see release notes for more information.
Tag the release series branch with the SemVer version of the release, e.g., v2.2.1. Ensure the tag is signed according to the general rules, and push it to the remote repository.
```
git tag -s -m "v2.2.1" v2.2.1
git push origin v2.2.1
```
Confirm that the CI builds and releases the newly tagged version.
Once the release is complete, update the release notes on GitHub with the release notes prepared in step 2.
Post a message in the #flux CNCF Slack channel

Distribution: release candidates

In some cases, it may be necessary to release a release candidate of the distribution.

To create a first release candidate, follow the steps to create a minor release, but use the rc.X suffix for SemVer version to release (e.g., v2.2.0-rc.1).

Once the release series branch is created, subsequent release candidates and the final (non-RC) release should follow the procedure for patch releases.

Distribution: release notes

The release notes template for Flux distributions is available in the release-notes-template.md file.

Distribution: Release and EOL notice update

Release and support cadence information is published at https://endoflife.date/flux. The source of truth for that page is maintained in this Git repository. Patch releases should automatically be captured by the automation in place there in a matter of roughly one day after release.

New minor releases need to be added manually to the flux.md page. Create a PR updating the file accordingly.

Backport changes for patch releases

The Flux projects have a backport bot that automates the process of backporting changes from main to the release series branches. The bot is configured to backport pull requests that are labeled with backport:<release series> (e.g., backport:release/v2.1.x) and have been merged into main.

The label(s) are preferably added to the pull request before it is merged into main. If the pull request is merged into main without labeling, they can still be added to the pull request after it has been merged.

The backport bot will automatically backport the pull request to the release series branch and create a pull request for the backport. It will comment on the pull request with a link to the backport pull request.

If the backport bot is unable to backport a pull request automatically (for example, due to conflicts), it will comment on the pull request with instructions on how to backport the pull request manually.

Manual backporting

In some cases, the backport bot may not be suitable for backporting a pull request. For example, if the pull request contains a series of changes of which a subset should be backported. In these cases, the pull request should be backported manually.

To backport a pull request manually, create a new branch from the release series branch (e.g., release/v2.1.x) and cherry-pick the commits from the pull request into the new branch. Push the new branch to the remote repository and create a pull request to merge it into the release series branch.

git pull origin release/v2.1.x
git switch -c backport-<pull request number>-to-v2.1.x release/v2.1.x
git cherry-pick -x <commit hash>
# Repeat the cherry-pick command for each commit to backport
git push origin backport-<pull request number>-to-v2.1.x

Flux – Flux releases

Flux: Flux controller releases

API versioning

Alpha version

Beta version

Stable version

Controller versioning

Release candidates

Patch releases

Minor releases

Major releases

Release cadence

Supported releases

Release artifacts

Flux: Flux shared packages releases

Release versioning

Release candidates

Patch releases

Minor releases

Major releases

Supported releases

Deprecation policy

Flux: Flux release procedures

Table of contents

General rules

Signing releases

Component types

Shared packages

Controllers

Controllers: minor releases

Controllers: patch releases

Controllers: release candidates

Controllers: preview releases

Distribution

Distribution: minor releases

Distribution: minor release website

Distribution: patch releases

Distribution: release candidates

Distribution: release notes

Distribution: Release and EOL notice update

Backport changes for patch releases

Manual backporting