Skip to content

📖 Update release support and compatibility info #3622

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 3, 2025
+74 −16
Merged

📖 Update release support and compatibility info #3622

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9550758
Update release support and compatibility info
fabriziopandini Aug 28, 2025
e91bc41
Address feedback
fabriziopandini Sep 2, 2025
34ee951
More feedback
fabriziopandini Sep 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 74 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,28 +29,86 @@ Check out the [getting started guide](./docs/getting_started.md) for launching a

------

## Compatibility with Cluster API and Kubernetes Versions
# CAPV release support

This provider's versions are compatible with the following versions of Cluster API:
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.
The CAPV release calendar will be aligned as much as possible to the Kubernetes and the Cluster API release dates plus an offset for
performing test/validation after K8s/CAPI release are available (tentatively one or two weeks after both K8s and CAPI release are available).

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

As CAPV doesn't dictate supported K8s versions, and it supports whatever CAPI supported, about the provider's compatibility with K8s versions, please refer
to [CAPI Supported Kubernetes Versions](https://cluster-api.sigs.k8s.io/reference/versions.html).
- Have CI signal with E2E tests, unit tests, CVE scans etc.
- Accept bug fixes, perform golang or dependency bumps, etc.
- Cut patch releases when necessary.
- 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.

Basically:
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.

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

**NOTES:**
* We aim to cut a CAPV minor release approximately one week after the corresponding CAPI minor release is out.
* 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.
- The first eight months of this timeframe will be considered the standard support period for a minor release.
- The next four months the minor release will be considered in maintenance mode.
- 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.

The table below documents support matrix for Cluster API provider vSphere versions (older versions omitted).

| Minor Release | Status | Supported Until (including maintenance mode) |
|---------------|-------------------------|--------------------------------------------------------------------------------------|
| v1.14.x | Standard support period | in maintenance mode when v1.16.0 will be released, EOL when v1.17.0 will be released |
| v1.13.x | Standard support period | in maintenance mode when v1.15.0 will be released, EOL when v1.16.0 will be released |
| v1.12.x | Maintenance mode | Maintenance mode v1.14.0 release date, EOL when v1.15.0 will be released |
| v1.11.x | EOL | EOL since v1.14.0 release date |
| v1.10.x | EOL | EOL since v1.13.0 release date |
| v1.9.x | EOL | EOL since v1.12.0 release date |

## Compatibility with Cluster API

Only a limited set of combinations between releases of CAPV and Cluster API are tested on CI and thus actively
supported:

| CAPV version | CAPI version used in CI |
|--------------|:-----------------------:|
| CAPV v1.12 | CAPI v1.9 |
| CAPV v1.13 | CAPI v1.10 |
| CAPV v1.14 | CAPI v1.11 |

Other CAPV/CAPI version combinations might work, but it is up to the users to validate those combinations;
also please be aware that in case of a CAPI/CAPV combination not listed above, support will be provided at best effort.

Following info should be used when identifying possible CAPV/CAPI version combinations outside the table above:

Compatibility between CAPV and Cluster API depends on which Cluster API contract versions is supported by CAPI and by
which contract version is implemented in CAPV.

The following table documents the Cluster API contract versions implemented by supported CAPV versions:

| | Cluster API contract version v1beta1 | Cluster API contract version v1beta1 |
|------------|:------------------------------------:|:------------------------------------:|
| CAPV v1.12 | ✓ | x |
| CAPV v1.13 | ✓ | x |
| CAPV v1.14 | ✓ | x |

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).

Additionally, each version of CAPV requires a specific API version to served by Cluster API, and this
further reduces the number of valid combinations.

The table below documents CAPI API version required by supported CAPV versions.

| CAPV version | Requires CAPI API version |
|--------------|:-------------------------:|
| CAPV v1.12 | v1beta1 |
| CAPV v1.13 | v1beta1 |
| CAPV v1.14 | v1beta2 |

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).

## Compatibility with Kubernetes Versions

CAPV doesn't dictate supported K8s versions, but in practice compatibility with Kubernetes versions is limited by the
compatibility matrix of the Cluster API version you are using in combination with CAPV.

Please refer to Cluster API 's [Kubernetes versions matrix](https://cluster-api.sigs.k8s.io/reference/versions#kubernetes-versions-support).

## Kubernetes versions with published OVAs

Expand Down