From 41ba55634a24ed446a0f664ad2c4d109103dde5a Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Tue, 25 Oct 2022 18:21:59 +0300 Subject: [PATCH] Add controller release spec Signed-off-by: Stefan Prodan --- docs/README.md | 2 +- docs/release/controllers.md | 122 ++++++++++++++++++++++++++++++++++++ 2 files changed, 123 insertions(+), 1 deletion(-) create mode 100644 docs/release/controllers.md diff --git a/docs/README.md b/docs/README.md index 472c337b..f16c4016 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,4 +3,4 @@ ## Release Engineering - [Shared packages release specifications](release/pkg.md) - +- [Controllers release specifications](release/controllers.md) diff --git a/docs/release/controllers.md b/docs/release/controllers.md new file mode 100644 index 00000000..d3e20119 --- /dev/null +++ b/docs/release/controllers.md @@ -0,0 +1,122 @@ +# Flux controllers release spec + +The Flux controllers are +[Kubernetes operators](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/), +each controller has its own Git repository and release cycle. + +Controller repositories and their interdependencies: + +1. [fluxcd/source-controller](https://github.com/fluxcd/source-controller) + - dependencies: `github.com/fluxcd/pkg/runtime` +2. [fluxcd/kustomize-controller](https://github.com/fluxcd/kustomize-controller) + - dependencies: `github.com/fluxcd/source-controller/api`, `github.com/fluxcd/pkg/runtime` +3. [fluxcd/helm-controller](https://github.com/fluxcd/helm-controller) + - dependencies: `github.com/fluxcd/source-controller/api`, `github.com/fluxcd/pkg/runtime` +4. [fluxcd/notification-controller](https://github.com/fluxcd/notification-controller) + - dependencies: `github.com/fluxcd/pkg/runtime` +5. [fluxcd/image-reflector-controller](https://github.com/fluxcd/image-reflector-controller) + - dependencies: `github.com/fluxcd/pkg/runtime` +6. [fluxcd/image-automation-controller](https://github.com/fluxcd/image-automation-controller) + - dependencies: `github.com/fluxcd/source-controller/api`, `github.com/fluxcd/image-reflector-controller/api`, `github.com/fluxcd/pkg/runtime` + +## Release versioning + +The Flux controllers and their API packages are released by following the +[Go module version numbering](https://go.dev/doc/modules/version-numbers) 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: + +```shell +go get github.com/fluxcd/source-controller/api@v1.0.0 +``` + +To pull a controller container image: + +```shell +docker pull ghcr.io/fluxcd/source-controller:v1.0.0 +``` + +A Flux controller's Kubernetes Custom Resource Definitions follow the +[Kubernetes API versioning](https://kubernetes.io/docs/reference/using-api/#api-versioning) scheme: + +- `v1apha1` experimental API +- `v1beta1` 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: + +1. Checkout the `main` branch and pull changes from remote. +2. Create a `api/` tag and push it to remote. +3. Create a new branch from `main` i.e. `release-`. This + will function as your release preparation branch. +4. Update the `github.com/fluxcd/-controller/api` version in `go.mod` +5. 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 `` 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 +and your public key must be uploaded to GitHub.