Skip to content

Remove v1beta1 apiVersion / IPAM & Runtime v1alpha1 #11920

Open

Description

@sbueringer

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.

Tasks:

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

Activity

  1. added
    needs-priorityIndicates an issue lacks a `priority/foo` label and requires one.
    needs-kindIndicates a PR lacks a `kind/foo` label and requires one.
    needs-triageIndicates an issue or PR lacks a `triage/foo` label and requires one.
    on Mar 3, 2025
  2. sbueringer commented on Mar 3, 2025

    @sbueringer
    MemberAuthor

    /triage accepted
    /assign
    /lifecycle frozen

  3. added
    lifecycle/frozenIndicates that an issue or PR should not be auto-closed due to staleness.
    triage/acceptedIndicates an issue or PR is ready to be actively worked on.
    and removed
    needs-triageIndicates an issue or PR lacks a `triage/foo` label and requires one.
    on Mar 3, 2025
  4. added
    priority/important-longtermImportant over the long term, but may not be staffed and/or may need multiple releases to complete.
    kind/cleanupCategorizes issue or PR as related to cleaning up code, process, or technical debt.
    on Mar 3, 2025
  5. removed
    needs-priorityIndicates an issue lacks a `priority/foo` label and requires one.
    needs-kindIndicates a PR lacks a `kind/foo` label and requires one.
    on Mar 3, 2025
  6. sbueringer commented on Mar 3, 2025

    @sbueringer
    MemberAuthor

    /milestone v1.11

  7. added this to the v1.11 milestone on Mar 3, 2025
  8. added
    priority/backlogHigher priority than priority/awaiting-more-evidence.
    and removed
    priority/important-longtermImportant over the long term, but may not be staffed and/or may need multiple releases to complete.
    on Mar 5, 2025
  9. changed the title [-]Remove v1beta1 apiVersion[/-] [+]Remove v1beta1 apiVersion / IPAM & Rumtime v1alpha1[/+] on May 22, 2025
  10. modified the milestones: v1.11, v1.14 on Sep 12, 2025
  11. JoelSpeed commented on Dec 12, 2025

    @JoelSpeed
    Contributor

    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

  12. sbueringer commented on Dec 16, 2025

    @sbueringer
    MemberAuthor

    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

  13. mnaser commented on Dec 30, 2025

    @mnaser

    If we're writing something that consumes the runtime hooks/API, does it need to use v1beta1 until those backend changes are done or they are not necessary?

  14. sbueringer commented on Dec 31, 2025

    @sbueringer
    MemberAuthor

    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)

  15. changed the title [-]Remove v1beta1 apiVersion / IPAM & Rumtime v1alpha1[/-] [+]Remove v1beta1 apiVersion / IPAM & Runtime v1alpha1[/+] on Feb 16, 2026
  16. fabriziopandini commented on Mar 2, 2026

    @fabriziopandini
    Member

    Extended the plan to give more room for the community/providers to catch up

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

kind/cleanupCategorizes 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.priority/backlogHigher priority than priority/awaiting-more-evidence.triage/acceptedIndicates an issue or PR is ready to be actively worked on.

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions