Skip to content

Latest commit

 

History

History
142 lines (104 loc) · 8.9 KB

v1.10-to-v1.11.md

File metadata and controls

142 lines (104 loc) · 8.9 KB

Cluster API v1.10 compared to v1.11

This document provides an overview over relevant changes between Cluster API v1.10 and v1.11 for maintainers of providers and consumers of our Go API.

We also recommend to (re)read the Improving status in CAPI resources proposal because most of the changes described below are a consequence of the work for implementing this proposal.

Go version

  • The Go version used by Cluster API is Go 1.23.x

API Changes

  • v1beta1 API version is now deprecated and it will be removed tentatively in August 2026
  • v1beta2 API version has been introduced; notable changes are:
    • The transition to the new K8s aligned conditions using metav1.Conditions types and the new condition semantic has been completed for all Kinds:
      • status.conditions has been replaced with status.v1beta2.conditions
      • the old status.conditions will continue to exist temporarily under status.deprecated.v1beta1 for the sake of down conversions and to provide a temporary option for users willing to continue using old conditions.
    • Support for terminal errors has been dropped from all Kinds
      • status.failureReason and status.failureMessage will continue to exist temporarily under status.deprecated.v1beta1 for the sake of down conversions and to provide a temporary option for users willing to continue using old conditions.
    • Informations about the initial provisioning process are now surfacing under status.initialization for both Cluster, Machine and KubeadmControlPlane Kinds.
    • All the resources handling machine replicas have now a consistent set of replica counters based on corresponding conditions defined at machine level.
      • status.readyReplicas, status.availableReplicas, status.upToDateReplicas on MachineDeployments, MachineSet and KubeadmControlPlane
      • The Cluster resource reports replica counters for both control plane and worker machines.

Cluster API Contract changes

  • v1beta1 version of the Cluster API contract is now deprecated
    • In order to ease the transition to the new v1beta2 version of the Cluster API contract, v1beta2 version will implement temporarily compatibility with the deprecated v1beta1 version of the Cluster API contract
    • Compatibility support for the v1beta1 version of the Cluster API contract will be removed tentatively in August 2026
    • After compatibility support for the v1beta1 version of the Cluster API contract is removed, providers which are implementing the v1beta1 contract will stop to work (they will work only with older versions of Cluster API).
  • v1beta2 version of the Cluster API contract has been introduced; notable changes are:
    • The transition to the new K8s aligned conditions using metav1.Conditions types and the new condition semantic has been completed.
      • The fact that Providers are not required to implement conditions remains valid
      • In case a provider implements conditions, Cluster API doesn't require anymore usage of a specific condition type, even if transition to metav1.Conditions is highly recommended.
    • Support for terminal errors has been dropped.

See provider contracts for more details.

Deprecation

  • v1beta1 API version is deprecated and it will be removed tentatively in August 2026
    • All the fields under status.deprecated.v1beta1 in the new v1beta2 API are deprecated and whey will be removed
  • v1beta1 conditions utils are now deprecated, and will removed as soon as v1beta1 API will be removed
  • v1beta1 support in the patch helper is now deprecated, and will removed as soon as v1beta1 API will be removed

Removals

There are no removals in the CAPI v1.11 version.

Please, also keep in mind future removals:

  • v1beta1 API version will be removed tentatively in August 2026
  • Starting from the CAPI release when v1beta1 removal will happen (tentative Aug 2026), the Cluster API project will remove the Cluster API condition type, the util/conditions package, the code handling conditions in util/patch.Helper and everything related to the custom Cluster API v1beta.Condition type.
  • Compatibility support for the v1beta1 version of the Cluster API contract will be removed tentatively in August 2026

Other

Suggested changes for providers

  • We highly recommend providers to start planning the move to the new v1beta2 version of the Cluster API contract; the transition MUST be completed before compatibility support for the v1beta1 version of the Cluster API contract will be removed tentatively in August 2026

  • We highly recommend providers to define their future strategy for condition management; also in this case the transition to the new condition management strategy MUST be completed before compatibility support for the v1beta1 version of the Cluster API contract will be removed tentatively in August 2026 Available options are:

    • Migrate to metav1.Conditions like Cluster API (recommended)
    • Replace Cluster API's v1beta1 Conditions with a custom condition implementation that is compliant with what is required by the v1beta2 Cluster API contract.
      • Starting from the CAPI release when v1beta1 removal will happen (tentative August 2026), the Cluster API project will remove the Cluster API condition type, the util/conditions/deprecated/v1beta1 package, the code handling conditions in util/patch.Helper and everything related to the custom Cluster API v1beta.Condition type.

Please refer to following how to guides for additional details.

How to bump to CAPI V1.11 but keep implementing the deprecated v1beta1 contract

CAPI v1.11 implements the v1beta2 version of the Cluster API contract.

However, in order to ease the transition for providers, the v1beta2 version of the Cluster API contract temporarily preserves compatibility with the deprecated v1beta1 contract.

Provider's implementing the deprecated v1beta1 contract can leverage compatibility support without any change, but it is crucial for them to start planning for the implementation of the new v1beta2 version of the Cluster API contract as soon a possible.

The implementation of the new v1beta2 version of the Cluster API contract MUST be completed before compatibility support for the v1beta1 version of the Cluster API contract will be removed tentatively in August 2026.

After compatibility support for the v1beta1 version of the Cluster API contract will be removed, providers which are still implementing the v1beta1 contract will stop to work (they will work only with older versions of Cluster API).

See provider contracts for more details.

How to bump to CAPI V1.11 but keep using deprecated v1beta1 conditions

A provider can continue to use deprecated v1beta1 conditions also after bumping to CAPI V1.11.

However:

  • It is required to use conditions type from the v1beta2 API version in order to keep using conditions utils.
  • Conditions utils for deprecated v1beta1 conditions have been moved to util/conditions/deprecated/v1beta1

Also, please note that starting from the CAPI release when v1beta1 removal will happen (tentative Aug 2026), the Cluster API project will remove the Cluster API condition type, the util/conditions/deprecated/v1beta1 package, the code handling conditions in util/patch.Helper and everything related to the custom Cluster API v1beta.Condition type.

See Suggested changes for providers for more details.

How to implement the new v1beta2 contract

We highly recommend providers to start planning the move to the new v1beta2 version of the Cluster API contract as soon as possible.

Implementing the new v1beta2 contract for providers is a two step operation:

  1. Implement changes defined for a specific provider type; See provider contracts for more details.
    • In most cases, v1beta2 contract introduced changes in the initialization completed, conditions, terminal failures rules; Also replicas rule is changed for control plane providers.
    • Considering the efforts to improve contract documentation in the last few releases, it is also highly recommended to check the implementation of all the other rules.
  2. Change the CRD annotation that document which Cluster API contract is implemented by your Provider.

How to start using metav1.conditions

We highly recommend providers define their future strategy for condition management as soon as possible.

If providers choose to migrate metav1.Conditions, the process described in Improving status in CAPI resources can be used as a reference about about how to implement a phased transition.