diff --git a/docs/book/src/developer/providers/contracts/control-plane.md b/docs/book/src/developer/providers/contracts/control-plane.md index e29214a5d497..d2d50083242f 100644 --- a/docs/book/src/developer/providers/contracts/control-plane.md +++ b/docs/book/src/developer/providers/contracts/control-plane.md @@ -333,61 +333,9 @@ documentation][scale]. In order to ease the transition for providers, the v1beta2 version of the Cluster API contract _temporarily_ preserves compatibility with the deprecated v1beta1 contract; compatibility will be removed tentatively in August 2026. -With regards to replicas: - -Cluster API will continue to temporarily support ControlPlane resource using the `status.ready` field to -report initialization completed. - -After compatibility with the deprecated v1beta1 contract will be removed, `status.ready` fields in -the ControlPlane resource will be ignored. - - - - diff --git a/docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md b/docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md index 84f5c852200f..7c4472cdcbd5 100644 --- a/docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md +++ b/docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md @@ -3,81 +3,267 @@ 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. +Any feedback or contributions to improve following documentation is welcome! + We also recommend to (re)read the [Improving status in CAPI resources](https://github.com/kubernetes-sigs/cluster-api/blob/4a2e16a3d71d99a923b1f7f3a3efe03c299665fb/docs/proposals/20240916-improve-status-in-CAPI-resources.md) proposal because most of the changes described below are a consequence of the work for implementing this proposal. + +* [Cluster API v1.10 compared to v1.11](#cluster-api-v110-compared-to-v111) + * [Go version](#go-version) + * [Dependencies](#dependencies) + * [API Changes](#api-changes) + * [All CRDs](#all-crds) + * [Cluster](#cluster) + * [MachineDeployment](#machinedeployment) + * [MachineSet](#machineset) + * [MachinePool](#machinepool) + * [Machine](#machine) + * [MachineHealthCheck](#machinehealthcheck) + * [ClusterClass](#clusterclass) + * [KubeadmConfig](#kubeadmconfig) + * [KubeadmControlPlane](#kubeadmcontrolplane) + * [Cluster API Contract changes](#cluster-api-contract-changes) + * [Contract rules for InfraCluster](#contract-rules-for-infracluster) + * [Contract rules for InfraMachine](#contract-rules-for-inframachine) + * [Contract rules for BootstrapConfig](#contract-rules-for-bootstrapconfig) + * [Contract rules for ControlPlane](#contract-rules-for-controlplane) + * [Contract rules for IPAM provider](#contract-rules-for-ipam-provider) + * [Contract rules for MachinePool](#contract-rules-for-machinepool) + * [Deprecations](#deprecations) + * [Removals scheduled for future releases](#removals-scheduled-for-future-releases) + * [Suggested changes for providers](#suggested-changes-for-providers) + * [How to bump to CAPI V1.11 but keep implementing the deprecated v1beta1 contract](#how-to-bump-to-capi-v111-but-keep-implementing-the-deprecated-v1beta1-contract) + * [How to implement the new v1beta2 contract](#how-to-implement-the-new-v1beta2-contract) + * [How to bump to CAPI V1.11 but keep using deprecated v1beta1 conditions](#how-to-bump-to-capi-v111-but-keep-using-deprecated-v1beta1-conditions) + * [How to start using metav1.conditions](#how-to-start-using-metav1conditions) + * [Stage 1](#stage-1-) + * [Stage 2](#stage-2) + * [Stage 3](#stage-3) + + ## Go version -- The Go version used by Cluster API is Go 1.23.x +- The minimal Go version required to build Cluster API is v1.24.x +- The Go version used by Cluster API is v1.24.x + +## Dependencies + +- The Controller Runtime version used by Cluster API is v0.21.x +- The version of the Kubernetes libraries used by Cluster API is v1.33.x -### API Changes +## 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` based on metav1 condition types - - the old `status.conditions` based on custom cluster API condition types will continue to exist temporarily - under `status.deprecated.v1beta1.conditions` 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. - - The const values for `Failed` phase has been deprecated in the following enum types (controllers are not setting this value anymore): - - `cluster.status.phase` - - `machineDeployment.status.phase` - - `machinePool.status.phase` - - `machine.status.phase` - - 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`; please note that - - `status.readyReplicas` has now a new semantic based on machine's `Ready` condition - - `status.availableReplicas` has now a new semantic based on machine's `Available` condition - - `status.upToDateReplicas` has now a new semantic (and name) based on machine's `UpToDate` condition - - Temporarily, old replica counters will still be available under the `status.deprecated.v1beta1` struct; more specifically - - `status.deprecated.v1beta1.readyReplicas` with old semantic for `MachineDeployments`, `MachineSet` and `KubeadmControlPlane` - - `status.deprecated.v1beta1.availableReplicas` with old semantic for `MachineDeployments`, `MachineSet` - - `status.deprecated.v1beta1.unavailableReplicas` with old semantic for `MachineDeployments`, `KubeadmControlPlane` - - `status.deprecated.v1beta1.updatedReplicas` with old semantic (and name) for `MachineDeployments`, `KubeadmControlPlane` - - `status.deprecated.v1beta1.fullyLabeledReplicas` for `MachineSet` - - The `Cluster` resource reports replica counters for both control plane and worker machines. - - MachineDeployment `status.phases` are now computed using the same logic used for `ScalingUp` and `ScalingDown` conditions. +- v1beta2 API version has been introduced; see following paragraphs for more details +- If you are using the `runtime.cluster.x-k8s.io` API group, please be aware that + - `ExtensionConfig` v1alpha1 has been deprecated, and it will be removed in a following release. + - `ExtensionConfig` v1beta2 has been created (thus aligning with other Cluster API resources) + +### All CRDs + +- 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` based on metav1 condition types + - the old `status.conditions` based on custom cluster API condition types will continue to exist temporarily + under `status.deprecated.v1beta1.conditions` for the sake of down conversions and to provide a temporary option + for users willing to continue using old conditions. + +### Cluster + +- See changes that apply to [all CRDs](#all-crds) +- The `spec.topology.class` field has been renamed to `spec.topology.classRef.name` +- The `spec.topology.classNamespace` field has been renamed to `spec.topology.classRef.namespace` +- The `definitionFrom` field (deprecated since CAPI v1.8) has been removed from + - `spec.topology.variables` + - `spec.topology.controlPlane.variables.overrides` + - `spec.topology.workers.machineDeployments[].variables.overrides` + - `spec.topology.workers.machinePools[].variables.overrides` +- The `unhealthyConditions` field has been renamed to `unhealthyNodeConditions` in following struct: + - `spec.topology.controlPlane.machineHealthCheck` + - `spec.topology.workers.machineDeployments[].machineHealthCheck` +- Information about the initial provisioning process are now surfacing under the new `status.initialization` field. + - `status.infrastructureReady` has been replaced by `status.initialization.infrastructureProvisioned` + - `status.controlPlaneReady` has been replaced by `status.initialization.controlPlaneInitialized` +- New fields for replica counters have been added to the cluster object + - `status.controlPlane` now reports replica counters surfaced from the control plane object. + - `status.workers` now reports replica counters from `MachineDeployments` and standalone `MachineSet` and `Machines` +- Support for terminal errors has been dropped. + - `status.failureReason` and `status.failureMessage` will continue to exist temporarily under `status.deprecated.v1beta1`. + - The const values for `Failed` phase has been deprecated in the enum type for `status.phase` (controllers are not setting this value anymore) +- The `GetIPFamily` method (deprecated since CAPI v1.8) has been removed + +### MachineDeployment + +- See changes that apply to [all CRDs](#all-crds) +- The `spec.progressDeadlineSeconds` field (deprecated since CAPI v1.9) has been removed +- Replica counters are now consistent with replica counters from other resources + - `status.readyReplicas` has now a new semantic based on machine's `Ready` condition + - `status.availableReplicas` has now a new semantic based on machine's `Available` condition + - `status.upToDateReplicas` has now a new semantic (and name) based on machine's `UpToDate` condition + - Temporarily, old replica counters will still be available under the `status.deprecated.v1beta1` struct +- Support for terminal errors has been dropped. + - `status.failureReason` and `status.failureMessage` will continue to exist temporarily under `status.deprecated.v1beta1`. + - The const values for `Failed` phase has been deprecated in the enum type for `status.phase` (controllers are not setting this value anymore) +- The `status.phases` field is now computed using the same logic used for `ScalingUp` and `ScalingDown` conditions. + +### MachineSet + +- See changes that apply to [all CRDs](#all-crds) +- Replica counters fields are now consistent with replica counters from other resources + - `status.readyReplicas` has now a new semantic based on machine's `Ready` condition + - `status.availableReplicas` has now a new semantic based on machine's `Available` condition + - `status.upToDateReplicas` has now a new semantic (and name) based on machine's `UpToDate` condition + - Temporarily, old replica counters will still be available under the `status.deprecated.v1beta1` struct +- Support for terminal errors has been dropped. + - `status.failureReason` and `status.failureMessage` will continue to exist temporarily under `status.deprecated.v1beta1`. + +### MachinePool + +- See changes that apply to [all CRDs](#all-crds) +- Support for terminal errors has been dropped. + - `status.failureReason` and `status.failureMessage` will continue to exist temporarily under `status.deprecated.v1beta1`. + - The const values for `Failed` phase has been deprecated in the enum type for `status.phase` (controllers are not setting this value anymore) + +### Machine + +- See changes that apply to [all CRDs](#all-crds) +- Information about the initial provisioning process is now surfacing under the new `status.initialization` field. + - `status.infrastructureReady` has been replaced by `status.initialization.infrastructureProvisioned` + - `status.bootstrapReady` has been replaced by `status.initialization.bootstrapDataSecretCreated` +- Support for terminal errors has been dropped. + - `status.failureReason` and `status.failureMessage` will continue to exist temporarily under `status.deprecated.v1beta1`. + - The const values for `Failed` phase has been deprecated in the enum type for `status.phase` (controllers are not setting this value anymore) + +### MachineHealthCheck + +- See changes that apply to [all CRDs](#all-crds) +- The `spec.unhealthyConditions` field has been renamed to `spec.unhealthyNodeConditions` + +### ClusterClass + +- See changes that apply to [all CRDs](#all-crds) +- The `unhealthyConditions` field has been renamed to `unhealthyNodeConditions` in following struct: + - `spec.controlPlane.machineHealthCheck` + - `spec.workers.machineDeployments[].machineHealthCheck` +- The `builtin.cluster.classRef.Name` and `builtin.cluster.classRef.Namespace` variables have been added + - The `builtin.cluster.class` and `builtin.cluster.classNamespace` are deprecated and will be removed with the next apiVersion. +- The `builtin.cluster.network.ipFamily` variable has been removed and it cannot be used anymore in patches + +### KubeadmConfig + +- KubeadmConfig (and the entire CABPK provider) now implements the v1beta2 Cluster API contract. +- See changes that apply to [all CRDs](#all-crds) +- The `spec.useExperimentalRetryJoin` field (deprecated in CAPI v1.2!) has been removed. +- Information about the initial provisioning process is now surfacing under the new `status.initialization` field. + - `status.ready` has been replaced by `status.initialization.dataSecretCreated` +- Support for terminal errors has been dropped (see [dataSecretCreated](#cluster-api-contract-changes)). + - `status.failureReason` and `status.failureMessage` will continue to exist temporarily under `status.deprecated.v1beta1`. + +### KubeadmControlPlane + +- KubeadmControlPlane (and the entire KCP provider) now implements the v1beta2 Cluster API contract. +- See changes that apply to [all CRDs](#all-crds) +- Replica counters fields are now consistent with replica counters from other resources. + - `status.readyReplicas` has now a new semantic based on machine's `Ready` condition + - `status.availableReplicas` has now a new semantic based on machine's `Available` condition + - `status.upToDateReplicas` has now a new semantic (and name) based on machine's `UpToDate` condition + - Temporarily, old replica counters will still be available under the `status.deprecated.v1beta1` struct +- Information about the initial provisioning process is now surfacing under the new `status.initialization` field. + - `status.ready` has been dropped + - `status.initialized` has been replaced by `status.initialization.controlPlaneInitialized` +- Support for terminal errors has been dropped. + - `status.failureReason` and `status.failureMessage` will continue to exist temporarily under `status.deprecated.v1beta1`. -### Cluster API Contract changes +## 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, is only intended to ease the transition for providers, and it has following limitations: - - The Machine controller won't consider the presence of `status.failureReason` and `status.failureMessage` info - as "terminal failures" - - MachineHealthCheck controller won't consider the presence of `status.failureReason` and `status.failureMessage` to - determine when a Machine needs remediation. + - Compatibility is only intended to ease the transition for providers, and it has some limitations; please + read details in following paragraphs. - 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; as a consequence if a provider resources reports `status.failureReason` - and `status.failureMessage`, those info won't have any impact on the lifecycle of the corresponding resources as before. - - `status.failureReason` and `status.failureMessage` will temporarily keep surfacing into `status.deprecated.v1beta1` - struct of the corresponding resources. -See [provider contracts](../contracts/overview.md) for more details. +- v1beta2 version of the Cluster API contract has been introduced; see following paragraphs for more details + +### Contract rules for InfraCluster + +Following rules have been changed or are not supported anymore; please read corresponding notes about compatibility +for providers still implementing the v1beta1 contract. + +- [InfraCluster: initialization completed](../contracts/infra-cluster.md#infracluster-initialization-completed) +- [InfraCluster: conditions](../contracts/infra-cluster.md#infracluster-conditions) + - 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. +- [InfraCluster: terminal failures](../contracts/infra-cluster.md#infracluster-terminal-failures) + - The Cluster controller won't consider the presence of `status.failureReason` and `status.failureMessage` info + as "terminal failures" + +### Contract rules for InfraMachine + +Following rules have been changed or are not supported anymore; please read corresponding notes about compatibility +for providers still implementing the v1beta1 contract. + +- [InfraMachine: initialization completed](../contracts/infra-machine.md#inframachine-initialization-completed) +- [InfraMachine: conditions](../contracts/infra-machine.md#inframachine-conditions) + - 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. +- [InfraMachine: terminal failures](../contracts/infra-machine.md#inframachine-terminal-failures) + - The Machine controller won't consider the presence of `status.failureReason` and `status.failureMessage` info + as "terminal failures" + - MachineHealthCheck controller won't consider the presence of `status.failureReason` and `status.failureMessage` to + determine when a Machine needs remediation. + +### Contract rules for BootstrapConfig + +Following rules have been changed or are not supported anymore; please read corresponding notes about compatibility +for providers still implementing the v1beta1 contract. + +- [BootstrapConfig: initialization completed](../contracts/bootstrap-config.md#bootstrapconfig-initialization-completed) +- [BootstrapConfig: conditions](../contracts/bootstrap-config.md#bootstrapconfig-conditions) + - 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. +- [BootstrapConfig: terminal failures](../contracts/bootstrap-config.md#bootstrapconfig-terminal-failures) + - The Machine controller won't consider the presence of `status.failureReason` and `status.failureMessage` info + as "terminal failures" + - MachineHealthCheck controller won't consider the presence of `status.failureReason` and `status.failureMessage` to + determine when a Machine needs remediation. -### Deprecation +### Contract rules for ControlPlane + +Following rules have been changed or are not supported anymore; please read corresponding notes about compatibility +for providers still implementing the v1beta1 contract. + +- [ControlPlane: initialization completed](../contracts/control-plane.md#controlplane-initialization-completed) +- [ControlPlane: replicas](../contracts/control-plane.md#controlplane-replicas) +- [ControlPlane: conditions](../contracts/control-plane.md#controlplane-conditions) + - 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. +- [ControlPlane: terminal failures](../contracts/control-plane.md#controlplane-terminal-failures) + - The Cluster controller won't consider the presence of `status.failureReason` and `status.failureMessage` info + as "terminal failures" + +### Contract rules for IPAM provider + +TODO + +### Contract rules for MachinePool + +TODO + +## Deprecations - 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. This includes: - `status.deprecated.v1beta1.conditions` based on custom cluster API condition types - - `status.deprecated.v1beta1.failureReason` and `status.failureMessage` + - `status.deprecated.v1beta1.failureReason` + - `status.deprecated.v1beta1.failureMessage` - `status.deprecated.v1beta1.readyReplicas` with old semantic for `MachineDeployments`, `MachineSet` and `KubeadmControlPlane` - `status.deprecated.v1beta1.availableReplicas` with old semantic for `MachineDeployments`, `MachineSet` - `status.deprecated.v1beta1.unavailableReplicas` with old semantic for `MachineDeployments`, `KubeadmControlPlane` @@ -93,49 +279,81 @@ See [provider contracts](../contracts/overview.md) for more details. - `MachinePoolPhase`, used in `machinePool.status.phase` - `MachinePhase`, used in `machine.status.phase` -### Removals +## Removals scheduled for future releases -There are no removals in the CAPI v1.11 version. - -As documented in [Suggested changes for providers](#suggested-changes-for-providers), please also start planning for future removals: +As documented in [Suggested changes for providers](#suggested-changes-for-providers), it is highly recommended to start planning for 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. + will remove the Cluster API condition type, the `util/conditions/deprecated/v1beta1` package, + the `util/deprecated/v1beta1` package, the code handling old conditions in `util/patch.Helper` + and everything related to the custom Cluster API custom 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 +## 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 start using Cluster API v1beta2 types when bumping to CAPI v1.11. + This requires changing following import: -- 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 + ```go + import ( + ... + clusterv1 "sigs.k8s.io/cluster-api/api/v1beta1" + ) + ``` + + into: + + ```go + import ( + ... + clusterv1 "sigs.k8s.io/cluster-api/api/v1beta2" + ) + ``` + + Please refer to [API Changes](#api-changes) for more details about the changes introduced by this release. + + Note: it is technically possible for providers to keep using v1beta1 types from CAPI v1.11, but this is + not recommended (this approach was not tested during the implementation, we don't know if there are road blockers). + +- If providers are using Conditions from Cluster API resources, e.g. by looking at the ControlPlaneInitialized condition + on the Cluster object, we highly recommend providers to use new conditions instead of old ones. + Utils for working with new conditions ara available in the `sigs.k8s.io/cluster-api/util/conditions` package. + - To keep using old conditions from the Cluster object, temporarily present under `status.deprecated.v1beta1.conditions` + it is required to use utils from the `util/conditions/deprecated/v1beta1` package. + Please note that `status.deprecated.v1beta1.conditions` will be removed tentatively in August 2026. + +- We highly recommend providers to start planning the move to the new v1beta2 version of the Cluster API contract + for their own resources, e.g. in the AWSCluster or the AWSMachine resource; the transition MUST be completed before + compatibility support for the v1beta1 version of the Cluster API contract will be removed tentatively in August 2026 + +- Depending on which Cluster API contract version you are choosing to implement in the provider's own CRDs, please refer to: + * [How to bump to CAPI V1.11 but keep implementing the deprecated v1beta1 contract](#how-to-bump-to-capi-v111-but-keep-implementing-the-deprecated-v1beta1-contract) + * [How to implement the new v1beta2 contract](#how-to-implement-the-new-v1beta2-contract) + +- We highly recommend providers to define their future strategy for condition management for their own resources, e.g. + in the AWSCluster or the AWSMachine resource; 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. + - 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 `util/deprecated/v1beta1` package, + the code handling old conditions in `util/patch.Helper` and everything related to the custom Cluster API custom condition type. + +- Depending on which option you are choosing for condition management in the provider's own CRDs, please refer to: + * [How to bump to CAPI V1.11 but keep using deprecated v1beta1 conditions](#how-to-bump-to-capi-v111-but-keep-using-deprecated-v1beta1-conditions) + * [How to start using metav1.conditions](#how-to-start-using-metav1conditions) -#### How to bump to CAPI V1.11 but keep implementing the deprecated v1beta1 contract +### 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; a few limitations apply: -- The Machine controller won't consider the presence of `status.failureReason` and `status.failureMessage` info -as "terminal failures" -- MachineHealthCheck controller won't consider the presence of `status.failureReason` and `status.failureMessage` to -determine when a Machine needs remediation. +preserves compatibility with the deprecated v1beta1 contract; a few limitations apply, please read +[Cluster API Contract changes](#cluster-api-contract-changes) for more details. 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 @@ -147,38 +365,134 @@ support for the v1beta1 version of the Cluster API contract will be removed tent 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](../contracts/overview.md) for more details. +Please see [Cluster API Contract changes](#cluster-api-contract-changes) and [provider contracts](../contracts/overview.md) for more details. -#### How to bump to CAPI V1.11 but keep using deprecated v1beta1 conditions +### How to implement the new v1beta2 contract -A provider can continue to use deprecated v1beta1 conditions also after bumping to CAPI V1.11. +We highly recommend providers to start planning the move to the new v1beta2 version of the Cluster API contract as soon +as possible. -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` +Implementing the new v1beta2 contract for providers is a two step operation: +1. Implement changes defined for a specific provider type; See [Cluster API Contract changes](#cluster-api-contract-changes) and [provider contracts](../contracts/overview.md) 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. +2. While implementing the changes above, It is also highly recommended to check the implementation of all the other rules + (documentation for contract rules have been improved in recent releases, worth to take a look!). +3. Change the CRD annotation that document which Cluster API contract is implemented by your Provider. e.g. + +```yaml +apiVersion: apiextensions.k8s.io/v1 +kind: CustomResourceDefinition +metadata: + annotations: + cluster.x-k8s.io/v1beta2: + name: +``` + +### 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, but to do +so it is required to change following imports: + +```go +import ( + ... + "sigs.k8s.io/cluster-api/util/conditions" + "sigs.k8s.io/cluster-api/util/patch" +) +``` + +into: + +```go +import ( + ... + conditions "sigs.k8s.io/cluster-api/util/deprecated/v1beta1/conditions" + patch "sigs.k8s.io/cluster-api/util/deprecated/v1beta1/patch" +) +``` 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. +will remove the Cluster API condition type, the `util/conditions/deprecated/v1beta1` package, the `util/deprecated/v1beta1` package, +the code handling old conditions in `util/patch.Helper` and everything related to the custom Cluster API custom condition type. -See [Suggested changes for providers](#suggested-changes-for-providers) for more details. +This means that if a provider wants to keep using deprecated v1beta1 conditions after this date, they have to maintain their +own custom copy of the types and related utils. -#### How to implement the new v1beta2 contract +Please also note that the v1beta2 contract is not going to require a specific condition types, so it will be also possible +to use different custom conditions types, -We highly recommend providers to start planning the move to the new v1beta2 version of the Cluster API contract as soon -as possible. +See [Suggested changes for providers](#suggested-changes-for-providers) and [Cluster API Contract changes](#cluster-api-contract-changes) +for more details. -Implementing the new v1beta2 contract for providers is a two step operation: -1. Implement changes defined for a specific provider type; See [provider contracts](../contracts/overview.md) 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 -#### How to start using metav1.conditions +If providers choose to migrate `metav1.Conditions`, the process described in [Improving status in CAPI resources](https://github.com/kubernetes-sigs/cluster-api/blob/4a2e16a3d71d99a923b1f7f3a3efe03c299665fb/docs/proposals/20240916-improve-status-in-CAPI-resources.md) +can be used as a reference about how to implement a phased transition. -We highly recommend providers define their future strategy for condition management as soon as possible. +As a quick summary, transition should go through following phases: -If providers choose to migrate `metav1.Conditions`, the process described in [Improving status in CAPI resources](https://github.com/kubernetes-sigs/cluster-api/blob/4a2e16a3d71d99a923b1f7f3a3efe03c299665fb/docs/proposals/20240916-improve-status-in-CAPI-resources.md) -can be used as a reference about about how to implement a phased transition. +#### Stage 1 + +Add `status.v1beta2.conditions` to your API (existing conditions will remain at `status.conditions`) + +If you are at this stage, you must use following util packages from CAPI v1.11 (or following releases, see note below): + +```go +import ( + ... + conditions "sigs.k8s.io/cluster-api/util/deprecated/v1beta1/conditions" + v1beta2conditions "sigs.k8s.io/cluster-api/util/deprecated/v1beta1/conditions/v1beta2" + patch "sigs.k8s.io/cluster-api/util/deprecated/v1beta1/patch" +) +``` + +- the `conditions` package alias provides access to utils for managing `clusterv1beta1.Conditions` in `status.conditions` +- the `v1beta2conditions` package alias provides access to utils for managing `metav1.Conditions` in `status.v1beta2.conditions` +- the `patch` package alias provides access to utils for patching objects in this phase. + +Important! +All packages from the import above (all packages below `sigs.k8s.io/cluster-api/util/deprecated/v1beta1`) are going +to be removed from CAPI when the v1beta1 removal will happen (tentative Aug 2026). + +#### Stage 2 + +Create a new API version, swap old conditions and new conditions, implement conversions +- Move old conditions from `status.conditions` to `status.deprecated.v1beta1.conditions` +- Move new conditions from `status.v1beta2.conditions` to `status.conditions` + +If you are at this stage, you must use following util packages from CAPI v1.11 (or following releases, see note below): + +```go +import ( + ... + "sigs.k8s.io/cluster-api/util/conditions" + v1beta1conditions "sigs.k8s.io/cluster-api/util/conditions/deprecated/v1beta1" + "sigs.k8s.io/cluster-api/util/patch" +) +``` + +- the `conditions` package provides access to utils for managing `metav1.Conditions` in `status.conditions` +- the `v1beta1conditions` package alias provides access to utils for managing `clusterv1beta2.Conditions` in `status.deprecated.v1beta1.conditions` +- the `patch` package provides access to utils for patching objects in this phase + +Important! +The package `sigs.k8s.io/cluster-api/util/conditions/deprecated/v1beta1`" is going to be removed from CAPI when the +v1beta1 removal will happen (tentative Aug 2026). + +#### Stage 3 + +When removing the old API version, remove `status.deprecated.v1beta1` + +Following util packages from CAPI v1.11 (or following releases) should be still in use: + +```go +import ( + ... + "sigs.k8s.io/cluster-api/util/conditions" + "sigs.k8s.io/cluster-api/util/patch" +) +``` + +- the `conditions` package provides access to utils for managing `metav1.Conditions` in `status.conditions` +- the `patch` package provides access to utils for patching objects in this phase