Add Flux release spec
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
This commit is contained in:
Stefan Prodan
@@ -1,6 +0,0 @@
|
||||
# Flux Development Documentation
|
||||
|
||||
## Release Engineering
|
||||
|
||||
- [Shared packages release specifications](release/packages.md)
|
||||
- [Controllers release specifications](release/controllers.md)
|
||||
7
docs/release/README.md
Normal file
7
docs/release/README.md
Normal file
@@ -0,0 +1,7 @@
|
||||
# Flux Release Documentation
|
||||
|
||||
## Release specifications
|
||||
|
||||
- [Flux distribution](flux.md)
|
||||
- [Flux APIs and controllers](controllers.md)
|
||||
- [Flux shared libraries](packages.md)
|
||||
@@ -20,26 +20,27 @@ The Flux APIs (Kubernetes CRDs) follow the
|
||||
|
||||
### Alpha version
|
||||
|
||||
An alpha version API e.g. `v1alpha1` is considered experiment and should be used on
|
||||
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 controller release.
|
||||
The custom resources may require editing and re-creating after a CRD update.
|
||||
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 months period.
|
||||
|
||||
An alpha API is introduced when its proposal reaches the `implementable` phase in the
|
||||
[Flux RFC process](https://github.com/fluxcd/flux2/tree/main/rfcs).
|
||||
We encourage users to try out the alpha APIs and provide feedback which is extremely
|
||||
valuable during early stages of development.
|
||||
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 be used.
|
||||
|
||||
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
|
||||
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.
|
||||
@@ -49,7 +50,7 @@ A deprecated beta version is subject to removal after a six months period.
|
||||
|
||||
A stable version API e.g. `v2` is considered feature complete.
|
||||
|
||||
Any changes to the object schema do not require editing or re-creating of custom resources.
|
||||
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.
|
||||
|
||||
@@ -110,9 +111,10 @@ 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.
|
||||
Flux controllers are at least released at the same rate as Kubernetes, following their cadence of three
|
||||
minor releases per year. 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.
|
||||
@@ -121,9 +123,11 @@ new feature or optimisation ahead of schedule.
|
||||
|
||||
For Flux controllers we support the last three minor releases.
|
||||
|
||||
Security fixes, may be backported to those three minor versions as patch 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:
|
||||
@@ -162,16 +166,15 @@ curl -sL https://github.com/fluxcd/<controller-name>/releases/download/<version>
|
||||
As a project maintainer, to release a controller and its API:
|
||||
|
||||
1. Checkout the `main` branch and pull changes from remote.
|
||||
2. Create a `api/<next semver>` tag and push it to remote.
|
||||
3. Create a new branch from `main` i.e. `release-<next semver>`. This
|
||||
2. Create a new branch from `main` i.e. `release-<next semver>`. This
|
||||
will function as your release preparation branch.
|
||||
4. Update the `github.com/fluxcd/<NAME>-controller/api` version in `go.mod`
|
||||
5. Add an entry to the `CHANGELOG.md` for the new release and change the
|
||||
3. Update the `github.com/fluxcd/<NAME>-controller/api` version in `go.mod`
|
||||
4. Add an entry to the `CHANGELOG.md` for the new release and change the
|
||||
`newTag` value in ` config/manager/kustomization.yaml` to that of the
|
||||
semver release you are going to make. Commit and push your changes.
|
||||
6. Create a PR for your release branch and get it merged into `main`.
|
||||
7. Create a `<next semver>` tag for the merge commit in `main` and
|
||||
push it to remote.
|
||||
5. Create a PR for your release branch and get it merged into `main`.
|
||||
6. Create a `api/<next semver>` tag for the merge commit in `main` and push it to remote.
|
||||
7. Create a `<next semver>` tag for the merge commit in `main` and push it to remote.
|
||||
8. Confirm CI builds and releases the newly tagged version.
|
||||
|
||||
**Note** that the Git tags must be cryptographically signed with your private key
|
||||
|
||||
173
docs/release/flux.md
Normal file
173
docs/release/flux.md
Normal file
@@ -0,0 +1,173 @@
|
||||
# Flux release spec
|
||||
|
||||
The Flux project repository [fluxcd/flux2](https://github.com/fluxcd/flux2) contains
|
||||
the Flux command-line tool source code and the Kubernetes manifests for
|
||||
bundling the [Flux controllers](controllers.md) into a distributable package.
|
||||
|
||||
## Release versioning
|
||||
|
||||
Flux is released by following the [semver](https://semver.org/) conventions:
|
||||
|
||||
- `vX.Y.Z-RC.W` release candidates e.g. `v2.0.0-RC.1`
|
||||
- `vX.Y.Z` stable releases e.g. `v2.0.0`
|
||||
|
||||
The Flux project maintains release branches for the most recent three minor releases
|
||||
e.g. `release-2.0`, `release-2.1` and `release-2.2`.
|
||||
|
||||
### 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 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.
|
||||
|
||||
Release candidates can be unstable and they are deprecated by subsequent RC or 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 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.
|
||||
|
||||
### 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 the Flux controllers or Kubernetes dependencies
|
||||
from one minor version to another.
|
||||
|
||||
In effect, this means a Flux minor version will be released at least every four months after each
|
||||
Kubernetes minor version release. To properly validate the Flux CLI and controllers against
|
||||
the latest Kubernetes version, we reserve a time window of at least two weeks for end-to-end testing.
|
||||
|
||||
### Major releases
|
||||
|
||||
Major releases are intended for drastic changes to the Flux behaviour or security stance.
|
||||
|
||||
A Flux 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 is at least released at the same rate as Kubernetes, following their cadence of three
|
||||
minor releases per year. After each Kubernetes minor release, the CLI and all controllers are
|
||||
tested against the latest Kubernetes version and are released at approximately two weeks after Kubernetes.
|
||||
The newly released Flux version offers support for Kubernetes N-2 minor versions.
|
||||
|
||||
Flux 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 the CLI and its controllers we support the last three minor releases.
|
||||
Critical bug fixes such as 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.
|
||||
|
||||
The Flux controllers are guaranteed to be compatible with each other
|
||||
within one minor version (older or newer) of Flux.
|
||||
|
||||
The `flux` command-line tool is supported within one minor version (older or newer) of Flux.
|
||||
|
||||
## Supported upgrades
|
||||
|
||||
Users can upgrade from any `v2.x` release to any other `v2.x` release (the latest patch version).
|
||||
|
||||
After upgrade, [Flux Custom Resources](controllers.md#api-versioning) may require editing,
|
||||
for which migration instructions are provided as part of the
|
||||
[changelog](#release-changelog).
|
||||
|
||||
We expect users to keep Flux up-to-date on their clusters using automation tools
|
||||
such as [Flux GitHub Actions](../../action) and
|
||||
[Renovatebot](https://docs.renovatebot.com/modules/manager/flux/).
|
||||
|
||||
Various vendors such as Microsoft Azure, D2iQ, Weaveworks and others offer a managed Flux service,
|
||||
and it's their responsibility to keep Flux up-to-date and free of CVEs.
|
||||
The Flux team communicates security issues to vendors as described in the
|
||||
[Coordinated Vulnerability Disclosure document](https://github.com/fluxcd/.github/blob/14b735cdb23ec80d528ff4f71e562405a2f00639/CVD_LIST.md).
|
||||
|
||||
## Kubernetes supported versions
|
||||
|
||||
The Flux CLI and controllers offer support for all Kubernetes versions supported upstream.
|
||||
|
||||
Every Flux release undergoes a series of conformance and end-to-end tests for
|
||||
the latest Kubernetes minor release. The test suite is run against
|
||||
[Kubernetes Kind](https://kind.sigs.k8s.io/) for both AMD64 and ARM64 distributions.
|
||||
|
||||
We expect users to keep Kubernetes up-to-date with the latest patch version of a
|
||||
supported minor release. Once a Kubernetes version reaches [end-of-life](https://endoflife.date/kubernetes),
|
||||
we can't guarantee the next Flux release will work with it,
|
||||
as we don't run end-to-end testing for EOL Kubernetes versions.
|
||||
|
||||
## Release artifacts
|
||||
|
||||
Each Flux release produces the following artifacts:
|
||||
|
||||
- Source code (GitHub Releases page)
|
||||
- Software Bill of Materials in SPDX format (GitHub Releases page)
|
||||
- Kubernetes manifests of all controllers (GitHub Releases page)
|
||||
- CLI binaries for Linux, macOS and Windows (GitHub Releases page)
|
||||
- Signed checksums of source code, SBOM and manifests (GitHub Releases page)
|
||||
- Multi-arch container images of the CLI (GitHub Container Registry and DockerHub)
|
||||
- OCI artifacts with the Kubernetes manifests (GitHub Container Registry and DockerHub)
|
||||
- CLI [Homebrew](https://brew.sh/) formulas for Linux and macOS
|
||||
|
||||
All the artifacts are cryptographically signed and can be verified with Cosign.
|
||||
|
||||
The release artifacts can be accessed based on the Flux version.
|
||||
|
||||
To verify and pull the Flux CLI container image:
|
||||
|
||||
```shell
|
||||
cosign verify ghcr.io/fluxcd/flux-cli:<version>
|
||||
docker pull ghcr.io/fluxcd/flux-cli:<version>
|
||||
```
|
||||
|
||||
To install the latest stable release of the Flux CLI with Homebrew:
|
||||
|
||||
```shell
|
||||
brew install fluxcd/tap/flux
|
||||
```
|
||||
|
||||
To download the Kubernetes manifests:
|
||||
|
||||
```shell
|
||||
cosign verify ghcr.io/fluxcd/flux-manifests:<version>
|
||||
flux pull artifact oci://ghcr.io/fluxcd/flux-manifests:<version> --output .
|
||||
```
|
||||
|
||||
## Release changelog
|
||||
|
||||
All released versions of Flux are published on [GitHub Releases page](https://github.com/fluxcd/flux2/releases)
|
||||
along with a list of changes from the previous release.
|
||||
|
||||
The changelog contains the following information:
|
||||
|
||||
- Security vulnerabilities fixes (if any)
|
||||
- Breaking changes and migration instructions (if any)
|
||||
- A summary of new features and improvements for the Flux APIs and controllers
|
||||
- Links to the changelog of each controller version included in a Flux release
|
||||
- A list of new features, improvements and bug fixes for the Flux CLI
|
||||
- A list of documentation additions
|
||||
|
||||
**Note** that the vulnerability disclosure procedure is explained on the [security page](https://fluxcd.io/security/).
|
||||
|
||||
## Release procedure
|
||||
|
||||
- `v2.X.Y-RC.Z` (Branch: `release-2.X`)
|
||||
- When the `main` branch is feature-complete for `v2.X`, we will cherrypick PRs essential to `v2.X` to the `release-2.X` branch.
|
||||
- We will cut the first [release candidate](#release-candidates) by tagging the `release-2.X` as `v2.X.0-RC.0`.
|
||||
- If we're not satisfied with `v2.X.0-RC.0`, we'll keep releasing RCs until all issues are solved.
|
||||
- `v2.X.0` (Branch: `release-2.X`)
|
||||
- The final release is cut from the `release-2.X` branch and tagged as `v2.X.0`.
|
||||
- `v2.X.Y, Y > 0` (Branch: `release-2.X`)
|
||||
- [Patch releases](#patch-releases) are released as we cherrypick commits from `main` into the `release-2.X` branch.
|
||||
- Flux controller updates (patch versions of a controller minor release included in `v2.X.0`) PRs are merged directly into the `release-2.X` branch.
|
||||
- A patch release is cut from the `release-2.X` branch and tagged as `v2.X.Y`.
|
||||
@@ -44,9 +44,9 @@ Patch releases should be used when updating dependencies such as `k8s.io/api` fr
|
||||
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.
|
||||
|
||||
Given that Kubernetes does not follow semver, a Kubernetes package minor version bump may introduce breaking changes.
|
||||
If a Kubernetes update requires a breaking change in a Flux package public API, then a major version release is necessary.
|
||||
If a [Kubernetes minor version](https://github.com/kubernetes/sig-release/blob/master/release-engineering/versioning.md)
|
||||
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user