Skip to content

Commit 20627fb

Browse files
fabriziopandinitylerauerbeck
fabriziopandini
authored and
tylerauerbeck
committed
📖 Update v1.11 support matrix (kubernetes-sigs#12131)
* Update v1.11 support matrix * Address comments * Drop line for the 1.12 version
1 parent 0d8fa0d commit 20627fb

File tree

1 file changed

+34
-32
lines changed

1 file changed

+34
-32
lines changed

‎docs/book/src/reference/versions.md

+34-32
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ For the sake of this document, the most important artifacts included in a Cluste
4242
- The Kubeadm Control Plane provider image
4343
- The clusterctl binary
4444

45-
The Cluster API team will release a new Cluster API version approximately every four months (3 releases each year).
45+
The Cluster API team will release a new Cluster API version approximately every four months (three releases each year).
4646
See [release cycle](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/release/release-cycle.md) and [release calendars](https://github.com/kubernetes-sigs/cluster-api/tree/main/docs/release/releases) for more details about Cluster API releases management.
4747

4848
The Cluster API team actively supports the latest two minor releases (N, N-1); support in this context means that we:
@@ -67,10 +67,10 @@ The table below documents support matrix for Cluster API versions (versions olde
6767

6868
| Minor Release | Status | Supported Until (including maintenance mode) |
6969
|---------------|-------------------------|---------------------------------------------------------------------------------------------|
70-
| v1.11.x | Under development | |
70+
| v1.11.x | Standard support period | in maintenance mode when v1.13.0 will be released, EOL when v1.14.0 will be released |
7171
| v1.10.x | Standard support period | in maintenance mode when v1.12.0 will be released, EOL when v1.13.0 will be released |
72-
| v1.9.x | Standard support period | in maintenance mode when v1.11.0 will be released, EOL when v1.12.0 will be released |
73-
| v1.8.x | Maintenance mode | Maintenance mode since 2025-04-22 - v1.10.0 release date, EOL when v1.11.0 will be released |
72+
| v1.9.x | Maintenance mode | Maintenance mode since 2025-08-12 - v1.11.0 release date, EOL when v1.12.0 will be released |
73+
| v1.8.x | EOL | EOL since 2025-08-12 - v1.11.0 release date |
7474
| v1.7.x | EOL | EOL since 2025-04-22 - v1.10.0 release date |
7575
| v1.6.x | EOL | EOL since 2024-12-10 - v1.9.0 release date |
7676
| v1.5.x | EOL | EOL since 2024-08-12 - v1.8.0 release date |
@@ -150,14 +150,14 @@ stopping and restarting the kube-controller-manager.
150150

151151
#### Cluster API release vs contract versions
152152

153-
Each Cluster API contract version defines a set of rules a provider is expected to comply with in order to interact with a specific Cluster API release.
153+
Each Cluster API contract version defines a set of rules a provider is expected to comply with to interact with a specific Cluster API release.
154154
Those rules can be in the form of CustomResourceDefinition (CRD) fields and/or expected behaviors to be implemented.
155155
See [provider contracts](../developer/providers/contracts/overview.md)
156156

157157
Each Cluster API release supports one contract version, and by convention the supported contract version matches
158158
the newest API version in the same Cluster API release.
159159

160-
A contract version might be temporarily compatible with older contract versions to ease transition of providers to
160+
A contract version might be temporarily compatible with older contract versions to ease the transition of providers to
161161
a new supported version; compatibility for older contract versions will be dropped when the older contract version is EOL.
162162

163163
<aside class="note">
@@ -181,12 +181,12 @@ providers of an older contract version)
181181

182182
</aside>
183183

184-
| Contract Version | Compatible with contract versions | Status | Supported Until |
185-
|------------------|-----------------------------------|-------------|---------------------------------------------------------------------------------------------|
186-
| v1beta2 | v1beta1 (temporarily) | Supported | After a newer API contract will be released |
187-
| v1beta1 | | Deprecated | Deprecated since CAPI v1.11; in v1.14, Aug 26 v1beta1 will no more be considered compatible |
188-
| v1alpha4 | | EOL | EOL since 2023-12-05 - v1.6.0 release date |
189-
| v1alpha3 | | EOL | EOL since 2023-07-25 - v1.5.0 release date |
184+
| Contract Version | Compatible with contract versions | Status | Supported Until |
185+
|------------------|-----------------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------|
186+
| v1beta2 | v1beta1 (temporarily) | Supported | After a newer API contract will be released |
187+
| v1beta1 | | Deprecated | Deprecated since CAPI v1.11; in v1.14, Aug 26 v1beta2 will drop compatibility with v1beta1 and v1beta1 will be considered EOL |
188+
| v1alpha4 | | EOL | EOL since 2023-12-05 - v1.6.0 release date |
189+
| v1alpha3 | | EOL | EOL since 2023-07-25 - v1.5.0 release date |
190190

191191
See [11920](https://github.com/kubernetes-sigs/cluster-api/issues/11920) for details about the v1beta1 removal plan.
192192

@@ -213,13 +213,13 @@ When a new Cluster API release is cut, we will document the Kubernetes version c
213213
has been tested with in the [table](#supported-versions-matrix-by-provider-or-component) below.
214214

215215
Each Cluster API minor release supports (when it's initially created):
216-
* 4 Kubernetes minor releases for the management cluster (N - N-3)
217-
* 6 Kubernetes minor releases for the workload cluster (N - N-5)
216+
* Four Kubernetes minor releases for the management cluster (N - N-3)
217+
* Six Kubernetes minor releases for the workload cluster (N - N-5)
218218

219219
When a new Kubernetes minor release is available, the Cluster API team will try to support it in an upcoming Cluster API
220220
patch release, thus extending the support matrix for the latest supported Cluster API minor release to:
221-
* 5 Kubernetes minor releases for the management cluster (N - N-4)
222-
* 7 Kubernetes minor releases for the workload cluster (N - N-6)
221+
* Five Kubernetes minor releases for the management cluster (N - N-4)
222+
* Seven Kubernetes minor releases for the workload cluster (N - N-6)
223223

224224
For example, Cluster API v1.7.0 would support the following Kubernetes versions:
225225
* v1.26.x to v1.29.x for the management cluster
@@ -233,7 +233,7 @@ For example, Cluster API v1.7.0 would support the following Kubernetes versions:
233233
Cluster API support for older Kubernetes version is not a replacement/alternative for upstream Kubernetes support policies!
234234

235235
Support for versions of Kubernetes which itself are out of support is limited to "Cluster API can start a Cluster with this Kubernetes version"
236-
and "Cluster API can upgrade to the next Kubernetes version"; it does not include any extended support to Kubernetes itself.
236+
and "Cluster API can upgrade to the next Kubernetes version"; it does not include any extended support to Kubernetes itself.
237237

238238
</aside>
239239

@@ -265,18 +265,18 @@ In some cases, also Cluster API and/or Cluster API providers are defining additi
265265
The following table defines the support matrix for the Cluster API core provider.
266266
See [Cluster API release support](#cluster-api-release-support) and [Kubernetes versions support](#kubernetes-versions-support).
267267

268-
| | v1.8, _Maintenance Mode_ | v1.9 | v1.10 |
268+
| | v1.9, _Maintenance Mode_ | v1.10 | v1.11 |
269269
|------------------|--------------------------|-------------------|-------------------|
270270
| Kubernetes v1.24 | | | |
271-
| Kubernetes v1.25 | ✓ (only workload) | | |
272-
| Kubernetes v1.26 | ✓ (only workload) | ✓ (only workload) | |
273-
| Kubernetes v1.27 | ✓ | ✓ (only workload) | ✓ (only workload) |
274-
| Kubernetes v1.28 | ✓ | ✓ | ✓ (only workload) |
275-
| Kubernetes v1.29 | ✓ | ✓ | ✓ |
271+
| Kubernetes v1.25 | | | |
272+
| Kubernetes v1.26 | ✓ (only workload) | | |
273+
| Kubernetes v1.27 | ✓ (only workload) | ✓ (only workload) | |
274+
| Kubernetes v1.28 | ✓ | ✓ (only workload) | ✓ (only workload) |
275+
| Kubernetes v1.29 | ✓ | ✓ | ✓ (only workload) |
276276
| Kubernetes v1.30 | ✓ | ✓ | ✓ |
277-
| Kubernetes v1.31 | ✓ >= v1.8.1 | ✓ | ✓ |
278-
| Kubernetes v1.32 | | ✓ >= v1.9.1 | ✓ |
279-
| Kubernetes v1.33 | | | ✓ >= v1.10.1 |
277+
| Kubernetes v1.31 | ✓ | ✓ | ✓ |
278+
| Kubernetes v1.32 | ✓ >= v1.9.1 | ✓ | ✓ |
279+
| Kubernetes v1.33 | | ✓ >= v1.10.1 | ✓ |
280280

281281
See also [Kubernetes version specific notes](#kubernetes-version-specific-notes).
282282

@@ -324,7 +324,7 @@ The Kubeadm Control Plane requires the Kubeadm Bootstrap provider of the same ve
324324

325325
#### Etcd API Support
326326

327-
The Kubeadm Control Plane provider communicates with the API server and etcd members of every Workload Cluster whose control plane it owns.
327+
The Kubeadm Control Plane provider communicates with the API server and etcd members of every Workload Cluster whose control plane it owns.
328328
All the Cluster API Kubeadm Control Plane providers currently supported are using [etcd v3 API](https://etcd.io/docs/v3.2/rfc/v3api/) when communicating with etcd.
329329

330330
#### CoreDNS Support
@@ -353,32 +353,34 @@ See [corefile-migration](https://github.com/coredns/corefile-migration)
353353
Cluster API has a vibrant ecosystem of awesome providers maintained by independent teams and hosted outside of
354354
the Cluster API [GitHub repository](https://github.com/kubernetes-sigs/cluster-api/).
355355

356-
To understand the list of supported version of a specific provider, its own Kubernetes support matrix, supported API versions,
356+
To understand the list of supported versions for a specific provider, its own Kubernetes support matrix, supported API versions,
357357
supported contract version and specific skip upgrade rules, please see its documentation. Please refer to [providers list](providers.md)
358358

359359
In general, if a provider version M says it is compatible with Cluster API version N, then it MUST be compatible
360360
with a subset of the Kubernetes versions supported by Cluster API version N.
361361

362362
### clusterctl
363363

364-
It is strongly recommended to always use the latest patch version of [clusterctl](../clusterctl/overview.md), in order to get all the fixes/latest changes.
364+
It is strongly recommended to always use the latest patch version of [clusterctl](../clusterctl/overview.md) to get all the fixes/latest changes.
365365

366366
In case of upgrades, clusterctl should be upgraded first and then used to upgrade all the other components.
367367

368368
## Annexes
369369

370370
### Kubernetes version Support and Cluster API deployment model
371371

372-
The most common deployment model for Cluster API assumes Core provider, Kubeadm Bootstrap provider, and Kubeadm Control Plane provider
373-
and at least one infrastructure provider running on the Management Cluster, all managing the lifecycle
372+
The most common deployment model for Cluster API assumes all providers are running on the Management Cluster and managing the lifecycle
374373
of a set of _separate_ Workload clusters.
375374

375+
"All providers" includes: the core provider, a Bootstrap provider, a Control Plane provider (optional),
376+
and at least one infrastructure provider.
377+
376378
![Management/Workload Separate Clusters](../images/management-workload-separate-clusters.png)
377379

378380
In this scenario, the Kubernetes version of the Management and Workload Clusters are allowed to be different.
379381
Additionally, Management Clusters and Workload Clusters can be upgraded independently and in any order.
380382

381-
In another deployment model for Cluster API, the Cluster API providers are used not only to managing the
383+
In another deployment model for Cluster API, the Cluster API providers are used not only to manage the
382384
lifecycle of _separate_ Workload clusters, but also to manage the lifecycle of the Management cluster itself.
383385
This cluster is also referred to as a "self-hosted" cluster.
384386

0 commit comments

Comments
 (0)