diff --git a/README.md b/README.md index f0256ebb..b19f9b3f 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ runtime for Flux v2. The APIs comprise Kubernetes custom resources, which can be created and updated by a cluster user, or by other automation tooling. -![overview](docs/_files/gitops-toolkit.png) +![overview](https://fluxcd.io/img/diagrams/gitops-toolkit.png) You can use the toolkit to extend Flux, or to build your own systems for continuous delivery -- see [the developer diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 5b1ab70e..00000000 --- a/docs/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# Flux v2 Documentation - -The documentation for `flux2` has moved to this repository: . - -[The Website's README](https://github.com/fluxcd/website/#readme) has information on how to - -- modify and extend documentation -- run the site locally -- publish changes - -and where all the individual pieces of content come from. - -It will be easier for us to maintain a coherent web presences (and merge all of Flux documentation) in one central repository. This was partly discussed in . - -## toolkit.fluxcd.io - -For historical reasons we are keeping a `_redirects` file in this directory. It defines how redirects from the old site `toolkit.fluxcd.io` to our new website work. Changes to this file need to be merged and a manual build triggered in the Netlify App. diff --git a/docs/_files/gitops-toolkit.png b/docs/_files/gitops-toolkit.png deleted file mode 100644 index cc5447b6..00000000 Binary files a/docs/_files/gitops-toolkit.png and /dev/null differ diff --git a/docs/_redirects b/docs/_redirects deleted file mode 100644 index 4860a76c..00000000 --- a/docs/_redirects +++ /dev/null @@ -1,18 +0,0 @@ -# individual rules -/core-concepts https://fluxcd.io/flux/concepts 301! -/contributing https://fluxcd.io/contributing 301! -/install.sh https://fluxcd.io/install.sh 301! - -# refer to https://github.com/fluxcd/flux2/discussions/367 -/dev-guides/* https://fluxcd.io/flux/gitops-toolkit/:splat 301! - - -# this is how things looked in the navbar anyway..? -/guides/faq-migration https://fluxcd.io/flux/migration/faq-migration 301! -/guides/flux-v1-automation-migration https://fluxcd.io/flux/migration/flux-v1-automation-migration 301! -/guides/flux-v1-migration https://fluxcd.io/flux/migration/flux-v1-migration 301! -/guides/helm-operator-migration https://fluxcd.io/flux/migration/helm-operator-migration 301! - - -# catch all -/* https://fluxcd.io/flux/:splat 301! diff --git a/docs/internal/diagrams.md b/docs/internal/diagrams.md deleted file mode 100644 index 138768cd..00000000 --- a/docs/internal/diagrams.md +++ /dev/null @@ -1,83 +0,0 @@ -# Flux Diagrams - -## Cluster sync from Git - -```mermaid -sequenceDiagram - actor me - participant git as Git

repository - participant sc as Flux

source-controller - participant kc as Flux

kustomize-controller - participant kube as Kubernetes

api-server - participant nc as Flux

notification-controller - me->>git: 1. git push - sc->>git: 2. git pull - sc->>sc: 3. build artifact for revision - sc->>kube: 4. update status for revision - sc-->>nc: 5. emit events - kube->>kc: 6. notify about new revision - kc->>sc: 7. fetch artifact for revision - kc->>kc: 8. build manifests to objects - kc-->>kc: 9. decrypt secrets - kc->>kube: 10. validate objects - kc->>kube: 11. apply objects - kc-->>kube: 12. delete objects - kc-->>kube: 13. wait for readiness - kc->>kube: 14. update status for revision - kc-->>nc: 15. emit events - nc-->>me: 16. send alerts for revision -``` - -## Helm release upgrade from Git - -```mermaid -sequenceDiagram - actor me - participant git as Git

repository - participant sc as Flux

source-controller - participant hc as Flux

helm-controller - participant kube as Kubernetes

api-server - participant nc as Flux

notification-controller - me->>git: 1. git push - sc->>git: 2. git pull - sc->>sc: 3. build chart for revision - sc->>kube: 4. update chart status - sc-->>nc: 5. emit events - kube->>hc: 6. notify about new revision - hc->>sc: 7. fetch chart - hc->>kube: 8. get values - hc->>hc: 9. render and customize manifests - hc-->>kube: 10. apply CRDs - hc->>kube: 11. upgrade release - hc-->>kube: 12. run tests - hc-->>kube: 13. wait for readiness - hc->>kube: 14. update status - hc-->>nc: 15. emit events - nc-->>me: 16. send alerts -``` - -## Image update to Git - -```mermaid -sequenceDiagram - actor me - participant oci as Image

repository - participant irc as Flux

image-reflector-controller - participant iac as Flux

image-automation-controller - participant kube as Kubernetes

api-server - participant nc as Flux

notification-controller - participant git as Git

repository - me->>oci: 1. docker push - irc->>oci: 2. list tags - irc->>irc: 3. match tags to policies - irc->>kube: 4. update status - irc-->>nc: 5. emit events - kube->>iac: 6. notify about new tags - iac->>git: 7. git clone - iac->>iac: 8. patch manifests with new tags - iac->>git: 9. git push - iac->>kube: 10. update status - iac-->>nc: 11. emit events - nc-->>me: 12. send alerts -``` - diff --git a/docs/internal/release.md b/docs/internal/release.md deleted file mode 100644 index 6fa08f03..00000000 --- a/docs/internal/release.md +++ /dev/null @@ -1,139 +0,0 @@ -# Flux release procedure - -The Flux Go modules and the GitOps Toolkit controllers are released by following the [semver](https://semver.org) conventions. - -Repositories subject to semver releases: - -1. [fluxcd/pkg](https://github.com/fluxcd/pkg) - - modules: `apis/meta`, `runtime`, various utilities - - dependencies: `k8s.io/*`, `sigs.k8s.io/controller-runtime` -1. [fluxcd/source-controller](https://github.com/fluxcd/source-controller) - - modules: `api` - - dependencies: `github.com/fluxcd/pkg/*` -1. [fluxcd/kustomize-controller](https://github.com/fluxcd/kustomize-controller) - - modules: `api` - - dependencies: `github.com/fluxcd/source-controller/api`, `github.com/fluxcd/pkg/*` -1. [fluxcd/helm-controller](https://github.com/fluxcd/helm-controller) - - modules: `api` - - dependencies: `github.com/fluxcd/source-controller/api`, `github.com/fluxcd/pkg/*` -1. [fluxcd/image-reflector-controller](https://github.com/fluxcd/image-reflector-controller) - - modules: `api` - - dependencies: `github.com/fluxcd/pkg/*` -1. [fluxcd/image-automation-controller](https://github.com/fluxcd/image-automation-controller) - - modules: `api` - - dependencies: `github.com/fluxcd/source-controller/api`, `github.com/fluxcd/image-reflector-controller/api`, `github.com/fluxcd/pkg/*` -1. [fluxcd/notification-controller](https://github.com/fluxcd/notification-controller) - - modules: `api` - - dependencies: `github.com/fluxcd/pkg/*` -1. [fluxcd/flux2](https://github.com/fluxcd/flux2) - - modules: `manifestgen` - - dependencies: `github.com/fluxcd/source-controller/api`, `github.com/fluxcd/kustomize-controller/api`, `github.com/fluxcd/helm-controller/api`, `github.com/fluxcd/image-reflector-controller/api`, `github.com/fluxcd/image-automation-controller/api`, `github.com/fluxcd/notification-controller/api`, `github.com/fluxcd/pkg/*` -1. [fluxcd/terraform-provider-flux](https://github.com/fluxcd/terraform-provider-flux) - - dependencies: `github.com/fluxcd/flux2/pkg/manifestgen` - -## Release procedure - -### Go packages - -The Go packages in [fluxcd/pkg](https://github.com/fluxcd/pkg) are dedicated modules, -each module has its own set of dependencies and release cycle. - -Release procedure for a package: - -1. Checkout the `main` branch and pull changes from remote. -1. Run `make release- VER=`. - -### Controllers - -A toolkit controller has a dedicated module for its API, the API module -has its own set of dependencies. - -Release procedure for a controller and its API: - -1. Checkout the `main` branch and pull changes from remote. -1. Create a `api/` tag and push it to remote. -1. Create a new branch from `main` i.e. `release-`. This - will function as your release preparation branch. -1. Update the `github.com/fluxcd/-controller/api` version in `go.mod` -1. 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. -1. Create a PR for your release branch and get it merged into `main`. -1. Create a `` tag for the merge commit in `main` and - push it to remote. -1. Confirm CI builds and releases the newly tagged version. - -### Flux - -Release procedure for Flux: - -1. Checkout the `main` branch and pull changes from remote. -1. Create a `` tag form `main` and push it to remote. -1. Confirm CI builds and releases the newly tagged version. - -## Upgrade Kubernetes modules - -Flux has the following Kubernetes dependencies: - -- `k8s.io/api` -- `k8s.io/apiextensions-apiserver` -- `k8s.io/apimachinery` -- `k8s.io/cli-runtime` -- `k8s.io/client-go` -- `sigs.k8s.io/controller-runtime` - -**Note** that all `k8s.io/*` packages must have the same version in `go.mod` e.g.: - -``` - k8s.io/api v0.20.2 - k8s.io/apiextensions-apiserver v0.20.2 - k8s.io/apimachinery v0.20.2 - k8s.io/cli-runtime v0.20.2 - k8s.io/client-go v0.20.2 -``` - -The specialised reconcilers depend on: - -- kustomize-controller: `sigs.k8s.io/kustomize/api` -- image-automation-controller: `sigs.k8s.io/kustomize/kyaml` -- helm-controller: `helm.sh/helm/v3` - -**Note** that the `k8s.io/*` version must be compatible with both `kustomize/api` and `helm/v3`. -If there is a breaking change in `client-go` we have to wait for Kustomize and Helm to upgrade first. - -### Upgrade procedure: - -`fluxcd/pkg`: - -1. Update the `k8s.io/*` version in `pkg/apis/meta/go.mod` -1. Release the `apis/meta` package -1. Update `apis/meta` version in `pkg/runtime/go.mod` -1. Update the `k8s.io/*` version in `pkg/runtime/go.mod` -1. Update `sigs.k8s.io/controller-runtime` version in `pkg/runtime/go.mod` -1. Release the `runtime` package - -`fluxcd/source-controller`: - -1. Update the `github.com/fluxcd/pkg/apis/meta` version in `source-controller/api/go.mod` and `source-controller/go.mod` -1. Update the `k8s.io/*` version in `source-controller/api/go.mod` and `source-controller/go.mod` -1. Update the `sigs.k8s.io/controller-runtime` version in `source-controller/api/go.mod` and `source-controller/go.mod` -1. Update the `github.com/fluxcd/pkg/runtime` version in `source-controller/go.mod` -1. Release the `api` package - -`fluxcd/-controller`: - -1. Update the `github.com/fluxcd/source-controller/api` version in `-controller/api/go.mod` and `-controller/go.mod` -1. Update the `github.com/fluxcd/pkg/apis/meta` version in `-controller/api/go.mod` and `-controller/go.mod` -1. Update the `k8s.io/*` version in `-controller/api/go.mod` and `-controller/go.mod` -1. Update the `github.com/fluxcd/pkg/runtime` version in `-controller/go.mod` -1. Release the `api` package - -`fluxcd/flux2`: - -1. Update the `github.com/fluxcd/*-controller/api` version in `flux2/go.mod` (automated with [GitHub Actions](../../.github/workflows/update.yaml)) -1. Update the `github.com/fluxcd/pkg/*` version in `flux2/go.mod` -1. Update the `k8s.io/*` and `github.com/fluxcd/pkg/runtime` version in `flux2/go.mod` - -`fluxcd/terraform-provider-flux`: - -1. Update the `github.com/fluxcd/flux2` version in `terraform-provider-flux/go.mod` (automated with [GitHub Actions](https://github.com/fluxcd/terraform-provider-flux/blob/main/.github/workflows/update.yaml)) diff --git a/docs/release/README.md b/docs/release/README.md new file mode 100644 index 00000000..cfc6dac4 --- /dev/null +++ b/docs/release/README.md @@ -0,0 +1,8 @@ +# Flux Release Documentation + +## Release specifications + +- [Flux distribution](flux.md) +- [Flux APIs and controllers](controllers.md) +- [Flux shared libraries](packages.md) +- [Flux release procedures](procedure.md) diff --git a/docs/release/controllers.md b/docs/release/controllers.md new file mode 100644 index 00000000..1459fa22 --- /dev/null +++ b/docs/release/controllers.md @@ -0,0 +1,151 @@ +# Flux controller releases + +The Flux controllers are +[Kubernetes operators](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/), +each controller has its own Git repository and release cycle (see below for details). + +Controller repositories and their interdependencies: + +1. [source-controller](https://github.com/fluxcd/source-controller) +2. [kustomize-controller](https://github.com/fluxcd/kustomize-controller) (imports `fluxcd/source-controller/api`) +3. [helm-controller](https://github.com/fluxcd/helm-controller) (imports `fluxcd/source-controller/api`) +4. [notification-controller](https://github.com/fluxcd/notification-controller) +5. [image-reflector-controller](https://github.com/fluxcd/image-reflector-controller) +6. [image-automation-controller](https://github.com/fluxcd/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](https://kubernetes.io/docs/reference/using-api/#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](https://github.com/fluxcd/flux2/tree/main/rfcs). +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](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` + +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](#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. diff --git a/docs/release/flux.md b/docs/release/flux.md new file mode 100644 index 00000000..c030392d --- /dev/null +++ b/docs/release/flux.md @@ -0,0 +1,145 @@ +# Flux releases + +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.x`, `release/2.1.x` and `release/2.2.x`. + +### 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 test 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 versions. + +### 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 backward-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. For in-depth information about this, please refer to the +[release cadence](#release-cadence) section of this document. + +### 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 approximately two weeks after Kubernetes. +The newly released Flux version offers 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. + +Flux may have more than three minor releases per year if maintainers decide to ship a +new feature or optimization 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) +- SLSA provenance attestations (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. + +## 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/). diff --git a/docs/release/packages.md b/docs/release/packages.md new file mode 100644 index 00000000..66354d13 --- /dev/null +++ b/docs/release/packages.md @@ -0,0 +1,74 @@ +# Flux shared package releases + +The Go packages in [github.com/fluxcd/pkg](https://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](https://go.dev/doc/modules/version-numbers) 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: + +```shell +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](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 + +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. + +```go +// Deprecated: use github.com/fluxcd/pkg/tar instead. +module github.com/fluxcd/pkg/untar +``` diff --git a/docs/release/procedure.md b/docs/release/procedure.md new file mode 100644 index 00000000..084340e6 --- /dev/null +++ b/docs/release/procedure.md @@ -0,0 +1,378 @@ +# Flux release procedures + +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. + +## Table of contents + +- [General rules](#general-rules) + + [Signing releases](#signing-releases) +- [Component types](#component-types) + + [Shared packages](#shared-packages) + + [Controllers](#controllers) + * [Minor releases](#controllers-minor-releases) + * [Patch releases](#controllers-patch-releases) + * [Release candidates](#controllers-release-candidates) + * [Preview releases](#controllers-preview-releases) + + [Distribution](#distribution) + * [Minor releases](#distribution-minor-releases) + * [Patch releases](#distribution-patch-releases) + * [Release candidates](#distribution-release-candidates) +- [Backport changes for patch releases](#backport-changes-for-patch-releases) + + [Manual backporting](#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: + +1. Safeguard your GPG private key, preferably using a hardware security key + like a YubiKey. +2. Use a subkey dedicated to signing releases, set an expiration date for + added security, and keep the master key offline. Refer to + [this guide](https://riseup.net/en/security/message-security/openpgp/best-practices#key-configuration) + 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](packages.md) as a project maintainer, follow these steps: + +1. Tag the `main` branch using SemVer. +2. Sign the tag according to the [general rules](#general-rules). +3. Push the signed tag to the upstream repository. + +Use the following commands as an example: + +```shell +git clone https://github.com/fluxcd/pkg.git +git switch main +git tag -s -m "/" "/" +git push origin "/" +``` + +In the commands above, `` represents the relative path to the directory +containing the `go.mod` file, and `` refers to the SemVer version of the +release. For instance, `runtime/v1.0.0` for [`fluxcd/pkg/runtime`](https://github.com/fluxcd/pkg/tree/main/runtime), +or `http/fetch/v0.1.0` for [`fluxcd/pkg/http/fetch`](https://github.com/fluxcd/pkg/tree/main/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: + +```shell +git switch +git tag -s -m "/-.1" "/-.1" +git push origin "/-.1" +``` + +### Controllers + +To release a [controller](controllers.md) as a project maintainer, follow the +steps below. Note that the release procedure differs depending on the type of +release. + +##### Controllers: minor releases + +1. Checkout the `main` branch and pull changes from the remote repository. + +2. Create a "release series" branch for the next minor SemVer range, e.g., + `release/v1.2.x`, and push it to the remote repository. + + ```shell + git switch -c release/v1.2.x main + ``` + +3. From the release series branch, create a release preparation branch for the + specific release. + + ```shell + git switch -c release-v1.2.0 release/v1.2.x + ``` + +4. Add an entry to `CHANGELOG.md` for the new release and commit the changes. + + ```shell + vim CHANGELOG.md + git add CHANGELOG.md + git commit -s -m "Add changelog entry for v1.2.0" + ``` + +5. Update `github.com/fluxcd/-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. + + ```shell + 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 + ``` + +6. Create a pull request for the release branch and merge it into the release + series branch (e.g., `release/v1.2.x`). + +7. Create `api/` and `` tags for the merge commit in + `release/v1.2.x`. Ensure the tags are signed according to the [general + rules](#general-rules), and push them to the remote repository. + + ```shell + 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 + ``` + +8. Confirm that the CI builds and releases the newly tagged version. + +9. Create a pull request for the release series branch and merge it into `main`. + +##### Controllers: patch releases + +1. 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](#backport-changes-for-patch-releases) section. + +2. From the release series branch, create a release preparation branch for the + specific patch release. + + ```shell + git pull origin release/v1.2.x + git switch -c release-v1.2.1 release/v1.2.1 + ``` + +3. Add an entry to `CHANGELOG.md` for the new release and commit the changes. + + ```shell + vim CHANGELOG.md + git add CHANGELOG.md + git commit -s -m "Add changelog entry for v1.2.1" + ``` + +4. Update `github.com/fluxcd/-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. + + ```shell + 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 + ``` + +5. Create a pull request for the release branch and merge it into the release + series branch (e.g., `release/v1.2.x`). + +6. Create `api/` and `` tags for the merge commit in + `release/v1.2.x`. Ensure the tags are signed according to the [general + rules](#general-rules), and push them to the remote repository. + + ```shell + 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 + ``` + +7. Confirm that the CI builds and releases the newly tagged version. + +8. Cherry-pick the changelog entry from the release series branch and create a + pull request to merge it into `main`. + + ```shell + git pull origin main + git switch -c pick-changelog-v1.2.1 main + git cherry-pick -x + git push origin pick-changelog-v1.2.1 + ``` + +#### Controllers: release candidates + +In some cases, it may be necessary to release a [release +candidate](controllers.md#release-candidates) of a controller. + +To create a first release candidate, follow the steps to create a [minor +release](#controllers-minor-releases), 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-patch-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. + +1. Navigate to `https://github.com/fluxcd/-controller/actions/workflows/release.yml`. + +2. Click the `Run workflow` button. + +3. Select the branch to release from the `Branch` dropdown. + +4. The default values for the `image tag` (`preview`) should be correct, but can + be changed if necessary. + +5. Click the green `Run workflow` button. + +6. 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](flux.md) as a project maintainer, follow the +steps below. + +Note that the Flux distribution contains multiple components, and you may need +to release [controllers](#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 + +1. 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. + +2. Create a "release series" branch for the next minor SemVer range, e.g., + `release/v2.2.x`, and push it to the remote repository. + + ```shell + git switch -c release/v2.2.x main + ``` + +3. Prepare the required release notes for this release, see [release + notes](#distribution-release-notes) for more information. + +4. 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](#general-rules), and push it to the remote repository. + + ```shell + git tag -s -m "v2.2.0" v2.2.0 + git push origin v2.2.0 + ``` + +5. Confirm that the CI builds and releases the newly tagged version. + +6. Once the release is complete, update the release notes on GitHub with the + release notes prepared in step 3. + +7. Post a message in the [`#flux` CNCF Slack channel](https://cloud-native.slack.com/archives/CLAJ40HV3) + announcing the release, and pin it. + +#### Distribution: patch releases + +1. 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](#backport-changes-for-patch-releases) section. + +2. Prepare the required release notes for this release, see [release + notes](#distribution-release-notes) for more information. + +3. 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](#general-rules), and push it to the remote repository. + + ```shell + git tag -s -m "v2.2.1" v2.2.1 + git push origin v2.2.1 + ``` + +4. Confirm that the CI builds and releases the newly tagged version. + +5. Once the release is complete, update the release notes on GitHub with the + release notes prepared in step 2. + +6. Post a message in the [`#flux` CNCF Slack channel](https://cloud-native.slack.com/archives/CLAJ40HV3) + +#### Distribution: release candidates + +In some cases, it may be necessary to release a [release candidate](flux.md#release-candidates) +of the distribution. + +To create a first release candidate, follow the steps to create a [minor +release](#distribution-minor-releases), 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-patch-releases). + +#### Distribution: release notes + +The release notes template for Flux distributions is available in the +[release-notes-template.md](https://github.com/fluxcd/flux2/blob/main/docs/release/release-notes-template.md) file. + +## 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:` (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. + +```shell +git pull origin release/v2.1.x +git switch -c backport--to-v2.1.x release/v2.1.x +git cherry-pick -x +# Repeat the cherry-pick command for each commit to backport +git push origin backport--to-v2.1.x +``` diff --git a/docs/release/release-notes-template.md b/docs/release/release-notes-template.md new file mode 100644 index 00000000..0b3a41de --- /dev/null +++ b/docs/release/release-notes-template.md @@ -0,0 +1,72 @@ +# Flux release note template + +This is a template for release notes. It is intended to be used as a +starting point for writing release notes for a new release. It should be copied +to a temporary file, and then edited to reflect the changes in the release. + +Once the release notes are complete, you can tag the release and push it to +GitHub. + +After the release is tagged, the CI will build the release artifacts and upload +them to the GitHub release page. The release notes can then be copied from the +temporary file to the GitHub release page. + +The release notes should be formatted using [Markdown](https://guides.github.com/features/mastering-markdown/), +and not make use of line breaks unless they function as paragraph breaks. + +For examples of release notes, including language and formatting of the release +highlights, see the [Flux release notes](https://github.com/fluxcd/flux2/releases). + +## GitHub release template + +The following template can be used for the GitHub release page: + +```markdown +## Highlights + + + +### Fixes and improvements + + + +## New documentation + + + +## Components changelog + +- -controller [v](https://github.com/fluxcd/-controller/blob//CHANGELOG.md + +## CLI changelog + + +``` + +In some scenarios, you may want to include specific information about API +changes and/or upgrade procedures. Consult [the formatting of +`v2.0.0-rc.1`](https://github.com/fluxcd/flux2/releases/tag/v2.0.0-rc.1) for +such an example. + +## Slack message template + +The following template can be used for the Slack release message: + +```markdown +:sparkles: *We are pleased to announce the release of Flux [](https://github.com/fluxcd/flux2/releases/tag//)!* + + + +:hammer_and_pick: *Fixes and improvements* + + + +:books: Documentation + + + +:heart: Big thanks to all the Flux contributors that helped us with this release! +``` + +For more concrete examples, see the pinned messages in the [Flux Slack +channel](https://cloud-native.slack.com/archives/CLAJ40HV3). \ No newline at end of file