Skip to content

Commit 0c2eacf

Browse files
fabriziopandinifabriziopandini
authored
📖 Update release support and compatibility info (#3622)
* Update release support and compatibility info * Address feedback * More feedback
1 parent cf79c10 commit 0c2eacf

File tree

1 file changed

+74
-16
lines changed

1 file changed

+74
-16
lines changed

‎README.md‎

Lines changed: 74 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -29,28 +29,86 @@ Check out the [getting started guide](./docs/getting_started.md) for launching a
2929

3030
------
3131

32-
## Compatibility with Cluster API and Kubernetes Versions
32+
# CAPV release support
3333

34-
This provider's versions are compatible with the following versions of Cluster API:
34+
A Cluster API provider vSphere release correspond to a release in the GitHub repository for this project, and the corresponding images published in the Kubernetes docker registry.
35+
The CAPV release calendar will be aligned as much as possible to the Kubernetes and the Cluster API release dates plus an offset for
36+
performing test/validation after K8s/CAPI release are available (tentatively one or two weeks after both K8s and CAPI release are available).
3537

36-
| | Cluster API v1beta1 (v1.6) | Cluster API v1beta1 (v1.7) | Cluster API v1beta1 (v1.8) | Cluster API v1beta1 (v1.9) |
37-
|----------------------|:--------------------------:|:--------------------------:|:--------------------------:|:--------------------------:|
38-
| CAPV v1beta1 (v1.9) | ✓ | x | x | x |
39-
| CAPV v1beta1 (v1.10) | x | ✓ | x | x |
40-
| CAPV v1beta1 (v1.11) | x | x | ✓ | x |
41-
| CAPV v1beta1 (v1.12) | x | x | x | ✓ |
38+
The CAPV team actively supports the latest two minor releases (N, N-1); support in this context means that we:
4239

43-
As CAPV doesn't dictate supported K8s versions, and it supports whatever CAPI supported, about the provider's compatibility with K8s versions, please refer
44-
to [CAPI Supported Kubernetes Versions](https://cluster-api.sigs.k8s.io/reference/versions.html).
40+
- Have CI signal with E2E tests, unit tests, CVE scans etc.
41+
- Accept bug fixes, perform golang or dependency bumps, etc.
42+
- Cut patch releases when necessary.
43+
- On top of supporting the N and N-1 releases, the CAPV team also maintains CI signal for the CAPV N-2 releases in case we have to do an emergency patch release.
4544

46-
Basically:
45+
If there is a need for an patch or an emergency patch, e.g. to fix a critical security issue, please bring this up to maintainers and it will be considered on a case-by-case basis.
4746

48-
- 4 Kubernetes minor releases for the management cluster (N - N-3)
49-
- 6 Kubernetes minor releases for the workload cluster (N - N-5)
47+
All considered, each CAPV minor release is supported for a period of roughly 12 months:
5048

51-
**NOTES:**
52-
* We aim to cut a CAPV minor release approximately one week after the corresponding CAPI minor release is out.
53-
* We aim to cut a CAPV minor or patch release with support for a new Kubernetes minor version approximately 3 business days after releases for CAPI and CPI that support the new Kubernetes version are available.
49+
- The first eight months of this timeframe will be considered the standard support period for a minor release.
50+
- The next four months the minor release will be considered in maintenance mode.
51+
- At the end of the four-month maintenance mode period, the minor release will be considered EOL (end of life) and cherry picks to the associated branch are to be closed soon afterwards.
52+
53+
The table below documents support matrix for Cluster API provider vSphere versions (older versions omitted).
54+
55+
| Minor Release | Status | Supported Until (including maintenance mode) |
56+
|---------------|-------------------------|--------------------------------------------------------------------------------------|
57+
| v1.14.x | Standard support period | in maintenance mode when v1.16.0 will be released, EOL when v1.17.0 will be released |
58+
| v1.13.x | Standard support period | in maintenance mode when v1.15.0 will be released, EOL when v1.16.0 will be released |
59+
| v1.12.x | Maintenance mode | Maintenance mode v1.14.0 release date, EOL when v1.15.0 will be released |
60+
| v1.11.x | EOL | EOL since v1.14.0 release date |
61+
| v1.10.x | EOL | EOL since v1.13.0 release date |
62+
| v1.9.x | EOL | EOL since v1.12.0 release date |
63+
64+
## Compatibility with Cluster API
65+
66+
Only a limited set of combinations between releases of CAPV and Cluster API are tested on CI and thus actively
67+
supported:
68+
69+
| CAPV version | CAPI version used in CI |
70+
|--------------|:-----------------------:|
71+
| CAPV v1.12 | CAPI v1.9 |
72+
| CAPV v1.13 | CAPI v1.10 |
73+
| CAPV v1.14 | CAPI v1.11 |
74+
75+
Other CAPV/CAPI version combinations might work, but it is up to the users to validate those combinations;
76+
also please be aware that in case of a CAPI/CAPV combination not listed above, support will be provided at best effort.
77+
78+
Following info should be used when identifying possible CAPV/CAPI version combinations outside the table above:
79+
80+
Compatibility between CAPV and Cluster API depends on which Cluster API contract versions is supported by CAPI and by
81+
which contract version is implemented in CAPV.
82+
83+
The following table documents the Cluster API contract versions implemented by supported CAPV versions:
84+
85+
| CAPV version | Implements Cluster API contract version |
86+
|--------------|:---------------------------------------:|
87+
| CAPV v1.12 | v1beta1 |
88+
| CAPV v1.13 | v1beta1 |
89+
| CAPV v1.14 | v1beta1 |
90+
91+
Contract versions supported by Cluster API are documented in the [versions](https://cluster-api.sigs.k8s.io/reference/versions#cluster-api-release-vs-contract-versions) page in the [Cluster API book](https://cluster-api.sigs.k8s.io).
92+
93+
Additionally, each version of CAPV requires a specific API version to served by Cluster API, and this
94+
further reduces the number of valid combinations.
95+
96+
The table below documents CAPI API version required by supported CAPV versions.
97+
98+
| CAPV version | Requires CAPI API version |
99+
|--------------|:-------------------------:|
100+
| CAPV v1.12 | v1beta1 |
101+
| CAPV v1.13 | v1beta1 |
102+
| CAPV v1.14 | v1beta2 |
103+
104+
API versions supported by Cluster API are documented in the [versions](https://cluster-api.sigs.k8s.io/reference/versions#cluster-api-release-vs-api-versions) page in the [Cluster API book](https://cluster-api.sigs.k8s.io).
105+
106+
## Compatibility with Kubernetes Versions
107+
108+
CAPV doesn't dictate supported K8s versions, but in practice compatibility with Kubernetes versions is limited by the
109+
compatibility matrix of the Cluster API version you are using in combination with CAPV.
110+
111+
Please refer to Cluster API 's [Kubernetes versions matrix](https://cluster-api.sigs.k8s.io/reference/versions#kubernetes-versions-support).
54112

55113
## Kubernetes versions with published OVAs
56114

0 commit comments

Comments
 (0)