kubernetes-sigs / kubernetes-sigs/cluster-api
Remove v1beta1 apiVersion / IPAM & Runtime v1alpha1
- Dominant language
- Go
- Stars
- 4.3k
- Forks
- 1.6k
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 113
Description
Tracking issue for v1beta1 apiVersion removal. This will stay around for a while.
For sake of simplicity, also IPAM v1alpha1 and Runtime v1alpha1 will be included
Context:
* CAPI supports 3 versions: for 2 versions we regularly release patch releases, for the 3rd one we create emergency patches on demand
* CAPI currently [tests up to n-3 => n upgrades](https://main.cluster-api.sigs.k8s.io/clusterctl/commands/upgrade#clusterctl-upgrade-test-coverage).
* Note: This is not well documented at the moment, but we should follow-up.
* Note: The n-3 => n policy in CAPI aligns to the corresponding policy in Kubernetes
* We want to make sure that removal of old apiVersions do not break the n-3 => n upgrade path. This means that we have to keep apiVersions around long enough that "storage version migration" and "managedField cleanup" are run.
**v1beta1**
| CAPI | Release date | v1beta1 | v1beta2 | Notes |
|-------|--------------|-----------------------|-----------------------|------------------|
| v1.9 | Dec 2024 | Served: true, Storage | | |
| v1.10 | April 2025 | Served: true, Storage | | |
| v1.11 | August 2025 | Served: true | Served: true, Storage | v1beta2 added |
| v1.12 | December 2025 | Served: true | Served: true, Storage | |
| v1.13 | April 2026 | Served: true | Served: true, Storage | |
| v1.14 | August 2026 | Served: true | Served: true, Storage | |
| v1.15 | December 2026 | Served: true | Served: true, Storage | |
| v1.16 | April 2027 | Served: false | Served: true, Storage | v1beta1 unserved |
| v1.17 | August 2027 | Served: false | Served: true, Storage | |
| v1.18 | December 2027 | Served: false | Served: true, Storage | |
| v1.19 | April 2028 | | Served: true, Storage | v1beta1 removed |
Notes:
* v1.11-v1.15: We have to keep v1beta1 served for 3 versions after introduction of v1beta2 according to the [Kubernetes deprecation policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/) + we decided to extend the deprecation period to give more room for the community/providers to catch up
* v1.16-v1.18: We have to keep v1beta1 around for 3 versions after it was unserved, to ensure that managedField cleanup is run even if someone upgrades from n-3 => n.
* Note for next time (v1beta2 removal): If we can rely on https://github.com/kubernetes/kubernetes/pull/136949 we might not have to keep the apiVersion unserved (or not that long)
Tasks:
* [x] [v1.11] Introduce v1beta2 (tracked elsewhere)
* [x] [v1.13] Prepare Runtime Hooks v1alpha1 types for v1beta1 removal: #13200
* [ ] [v1.16] Unserve v1beta1
* [ ] While doing this also unserve & deprecate IPAM v1alpha1
* [ ] [v1.19] Remove v1beta1
* [ ] [TBD] Consider removing managedField mitigation (https://github.com/kubernetes-sigs/cluster-api/pull/13338)
* Maybe wait until we can rely on the kube-apiserver fix: https://github.com/kubernetes/kubernetes/pull/136949
* Maybe even after that keep it for the Cluster object (we might still get before-first-apply there as the topology controller does an SSA write on the Cluster object)
Tasks after v1beta1 is removed:
* [ ] KubeadmConfig / KCP / etc.
* [ ] Remove "unique" CEL rule from extraArgs
* [ ] Remove validation that ControlPlaneComponentHealthCheckSeconds has to be the same for init/join configuration
* [ ] Remove --v1beta2 flag from clusterctl describe
* [ ] Cleanup: align all CRDs in util/test/builder package to v1beta2 contract
For more context, see: https://github.com/kubernetes-sigs/cluster-api/issues/11894
Contributor guide
Assessment
This issue has not been assessed yet.