Repository navigation
Open
Labels
kind/cleanupCategorizes issue or PR as related to cleaning up code, process, or technical debt.Categorizes issue or PR as related to cleaning up code, process, or technical debt.lifecycle/frozenIndicates that an issue or PR should not be auto-closed due to staleness.Indicates that an issue or PR should not be auto-closed due to staleness.priority/backlogHigher priority than priority/awaiting-more-evidence.Higher priority than priority/awaiting-more-evidence.triage/acceptedIndicates an issue or PR is ready to be actively worked on.Indicates an issue or PR is ready to be actively worked on.
Milestone
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.
- 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 + 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 Do not remove managedFields if conversion webhook fails kubernetes/kubernetes#136949 we might not have to keep the apiVersion unserved (or not that long)
Tasks:
- [v1.11] Introduce v1beta2 (tracked elsewhere)
- [v1.13] Prepare Runtime Hooks v1alpha1 types for v1beta1 removal: ⚠️ Bump Runtime Hooks v1alpha1 types to core CAPI v1beta2 #13200
- [v1.16] Unserve v1beta1
- While doing this also unserve & deprecate IPAM v1alpha1
- [v1.19] Remove v1beta1
- [TBD] Consider removing managedField mitigation (🐛 Mitigate managedFields apiserver issue for SSA #13338)
- Maybe wait until we can rely on the kube-apiserver fix: Do not remove managedFields if conversion webhook fails kubernetes/kubernetes#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)
- [TBD] Consider removing managedField mitigation (🐛 Mitigate managedFields apiserver issue for SSA #13338)
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: #11894
Metadata
Metadata
Assignees
Labels
kind/cleanupCategorizes issue or PR as related to cleaning up code, process, or technical debt.Categorizes issue or PR as related to cleaning up code, process, or technical debt.lifecycle/frozenIndicates that an issue or PR should not be auto-closed due to staleness.Indicates that an issue or PR should not be auto-closed due to staleness.priority/backlogHigher priority than priority/awaiting-more-evidence.Higher priority than priority/awaiting-more-evidence.triage/acceptedIndicates an issue or PR is ready to be actively worked on.Indicates an issue or PR is ready to be actively worked on.
Activity
sbueringer commentedon Mar 3, 2025
/triage accepted
/assign
/lifecycle frozen
sbueringer commentedon Mar 3, 2025
/milestone v1.11
[-]Remove v1beta1 apiVersion[/-][+]Remove v1beta1 apiVersion / IPAM & Rumtime v1alpha1[/+]JoelSpeed commentedon Dec 12, 2025
Nit on the timeline here, that we probably want to discuss for the next API version, is that it's generally advised (see api changes) not to introduce a new version AND make it the storage version within the same release.
For v1beta2, we should have added the v1beta2 APIs in v1.11, and then made them the storage version in v1.12. The rest of the timeline would be unaffected, but it would allow anyone who found an issue in v1.11 to downgrade back to v1.10
sbueringer commentedon Dec 16, 2025
Hm yeah. You're not wrong. We just have to also consider what that means for our CRD migrator component and how this plays out in combination with supporting up to n-3 => n upgrades.
I think supporting downgrades would be also more than just bumping the storage version later. E.g. thinking about things like managedField migration that we had to do a few times in the past. There's no way to retroactively add a reverse managedField migration to already released versions
mnaser commentedon Dec 30, 2025
If we're writing something that consumes the runtime hooks/API, does it need to use
v1beta1until those backend changes are done or they are not necessary?sbueringer commentedon Dec 31, 2025
You don't have to wait in my opinion. Please note that we want to make this change in v1.13: #13200
(So for now you have to handle the current v1alpha1 types and with v1.13 they would change. But in general you can use v1beta2 everywhere apart from handling the current embedded types of our structs)
[-]Remove v1beta1 apiVersion / IPAM & Rumtime v1alpha1[/-][+]Remove v1beta1 apiVersion / IPAM & Runtime v1alpha1[/+]fabriziopandini commentedon Mar 2, 2026
Extended the plan to give more room for the community/providers to catch up