mirror of
https://github.com/fluxcd/flux2.git
synced 2025-11-01 01:25:53 +08:00
Add API versioning spec
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
This commit is contained in:
Stefan Prodan
@ -7,44 +7,86 @@ 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`
|
||||
2. [fluxcd/kustomize-controller](https://github.com/fluxcd/kustomize-controller) (imports `fluxcd/source-controller/api`)
|
||||
3. [fluxcd/helm-controller](https://github.com/fluxcd/helm-controller) (imports `fluxcd/source-controller/api`)
|
||||
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`
|
||||
6. [fluxcd/image-automation-controller](https://github.com/fluxcd/image-automation-controller) (imports `fluxcd/source-controller/api` and `fluxcd/image-reflector-controller/api`)
|
||||
|
||||
## Release versioning
|
||||
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.
|
||||
|
||||
The Flux controllers and their API packages are released by following the
|
||||
## 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 experiment 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.
|
||||
|
||||
An alpha API is introduced after it 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.
|
||||
|
||||
### 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
|
||||
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 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.
|
||||
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 version API becomes deprecated once a subsequent stable version is released.
|
||||
Stable API versions are not subject to removal in any future release of 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 release artifacts can be accessed based on the controller name and version.
|
||||
|
||||
To import or update a controller API package in a Go project:
|
||||
|
||||
```shell
|
||||
go get github.com/fluxcd/source-controller/api@v1.0.0
|
||||
go get github.com/fluxcd/<controller-name>/api@<version>
|
||||
```
|
||||
|
||||
To pull a controller container image:
|
||||
|
||||
```shell
|
||||
docker pull ghcr.io/fluxcd/source-controller:v1.0.0
|
||||
docker pull ghcr.io/fluxcd/<controller-name>:<version>
|
||||
```
|
||||
|
||||
A Flux controller's Kubernetes Custom Resource Definitions follow the
|
||||
[Kubernetes API versioning](https://kubernetes.io/docs/reference/using-api/#api-versioning) scheme:
|
||||
To download a controller's Kubernetes Custom resource definitions:
|
||||
|
||||
- `v1apha1` experimental API
|
||||
- `v1beta1` release candidate (supported while v1 is not released)
|
||||
- `v1` stable release (supported)
|
||||
```shell
|
||||
curl -sL https://github.com/fluxcd/<controller-name>/releases/download/<version>/<controller-name>.crds.yaml
|
||||
```
|
||||
|
||||
### Release candidates
|
||||
|
||||
|
||||
Reference in New Issue
Block a user