kubernetes-sigs / kubernetes-sigs/cluster-api

Remove v1beta1 apiVersion / IPAM & Runtime v1alpha1

Open
#11,920 7 comments 0 reactions 1 assignee Claimed by @sbueringer View on GitHub
kind/cleanup lifecycle/frozen priority/backlog triage/accepted
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.