5.4 KiB
Flux controllers release spec
The Flux controllers are Kubernetes operators, each controller has its own Git repository and release cycle.
Controller repositories and their interdependencies:
- fluxcd/source-controller
- dependencies:
github.com/fluxcd/pkg/runtime
- dependencies:
- fluxcd/kustomize-controller
- dependencies:
github.com/fluxcd/source-controller/api
,github.com/fluxcd/pkg/runtime
- dependencies:
- fluxcd/helm-controller
- dependencies:
github.com/fluxcd/source-controller/api
,github.com/fluxcd/pkg/runtime
- dependencies:
- fluxcd/notification-controller
- dependencies:
github.com/fluxcd/pkg/runtime
- dependencies:
- fluxcd/image-reflector-controller
- dependencies:
github.com/fluxcd/pkg/runtime
- dependencies:
- fluxcd/image-automation-controller
- dependencies:
github.com/fluxcd/source-controller/api
,github.com/fluxcd/image-reflector-controller/api
,github.com/fluxcd/pkg/runtime
- dependencies:
Release versioning
The Flux controllers and their 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
To import or update a controller API package in a Go project:
go get github.com/fluxcd/source-controller/api@v1.0.0
To pull a controller container image:
docker pull ghcr.io/fluxcd/source-controller:v1.0.0
A Flux controller's Kubernetes Custom Resource Definitions follow the Kubernetes API versioning scheme:
v1apha1
experimental APIv1beta1
release candidate (supported while v1 is not released)v1
stable release (supported)
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 CVE 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.
Minor releases are used when updating Kubernetes dependencies such as k8s.io/api
from one minor version to another.
In effect, this means a minor version will be released for all Flux controllers approximately every three months after each Kubernetes minor version release.
To properly validate the controllers against the latest Kubernetes version, we reserve a time window of at least two weeks for Flux controllers end-to-end testing.
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 follow Kubernetes three releases per year cadence. After each Kubernetes minor release, all controllers are tested against the latest Kubernetes version and are released at approximately two weeks after Kubernetes. The newly released controllers offer support for Kubernetes N-2 minor versions.
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 backported to those three minor versions as patch releases, depending on severity and feasibility.
Release procedure
As a project maintainer, to release a controller and its API:
- Checkout the
main
branch and pull changes from remote. - Create a
api/<next semver>
tag and push it to remote. - Create a new branch from
main
i.e.release-<next semver>
. This will function as your release preparation branch. - Update the
github.com/fluxcd/<NAME>-controller/api
version ingo.mod
- Add an entry to the
CHANGELOG.md
for the new release and change thenewTag
value inconfig/manager/kustomization.yaml
to that of the semver release you are going to make. Commit and push your changes. - Create a PR for your release branch and get it merged into
main
. - Create a
<next semver>
tag for the merge commit inmain
and push it to remote. - Confirm CI builds and releases the newly tagged version.
Note that the Git tags must be cryptographically signed with your private key and your public key must be uploaded to GitHub.