From 5c7293dca21349f4153895c1d2611160249f1ed8 Mon Sep 17 00:00:00 2001 From: fabriziopandini Date: Fri, 16 May 2025 21:15:56 +0200 Subject: [PATCH 1/8] More documentation on v1.11 migration # Conflicts: # docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md --- .../providers/contracts/control-plane.md | 58 +-- .../providers/migrations/v1.10-to-v1.11.md | 489 ++++++++++++++---- 2 files changed, 399 insertions(+), 148 deletions(-) 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..4d4678121728 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,266 @@ 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 Kind](#all-kind) + * [Cluster](#cluster) + * [MachineDeployment](#machinedeployment) + * [MachineSet](#machineset) + * [MachinePool](#machinepool) + * [Machine](#machine) + * [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](#removals) + * [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.23.x +- The Go version used by Cluster API is v1.23.x + +## Dependencies -### API Changes +- 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 - 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 created (thus aligning with other Cluster API resources) + + ### All Kind + +- 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 applies to [all kind](#all-kind) +- The `spec.topology.class` has been renamed to `spec.topology.classRef.name` +- The `spec.topology.classNamespace` has been renamed to `spec.topology.classRef.namespace` +- The `definitionFrom` field (deprecated since CAPI v1.8) has been removed from + - `cluster.spec.topology.variables` + - `cluster.spec.topology.controlPlane.variables.override` + - `cluster.spec.topology.workers[].machineDeployments.variables.override` +- Informations about the initial provisioning process are now surfacing under `status.initialization` (see [dataSecretCreated](#cluster-api-contract-changes)). + - `status.infrastructureReady` has beed replaced by `status.initialization.infrastructureProvisioned` + - `status.controlPlaneReady` has beed replaced by `status.initialization.controlPlaneInitialized` +- Replica counters have been added to the cluster object + - `status.controlPlane` now reports replica counters surfaced from the control plane object (see [dataSecretCreated](#cluster-api-contract-changes)). + - `status.workers` now reports replica counters from `MachineDeployments` and standalone `MachineSet` and `Machines` +- 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`. + - The const values for `Failed` phase has been deprecated in the enum type for `cluster.status.phase` (controllers are not setting this value anymore) +- The `GetIPFamily` method (deprecated since CAPI v1.8) has been removed + +### MachineDeployment + +- See changes that applies to [all kind](#all-kind) +- 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 (see [dataSecretCreated](#cluster-api-contract-changes)). + - `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 `machineDeployment.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 applies to [all kind](#all-kind) +- 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 (see [dataSecretCreated](#cluster-api-contract-changes)). + - `status.failureReason` and `status.failureMessage` will continue to exist temporarily under `status.deprecated.v1beta1`. + +### MachinePool + +- See changes that applies to [all kind](#all-kind) +- 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 (see [dataSecretCreated](#cluster-api-contract-changes)). + - `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 `machinePool.status.phase` (controllers are not setting this value anymore) + +### Machine + +- See changes that applies to [all kind](#all-kind) +- Informations about the initial provisioning process are now surfacing under `status.initialization` (see [dataSecretCreated](#cluster-api-contract-changes)). + - `status.infrastructureReady` has beed replaced by `status.initialization.infrastructureProvisioned` + - `status.bootstrapReady` has beed replaced by `status.initialization.bootstrapDataSecretCreated` +- 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`. + - The const values for `Failed` phase has been deprecated in the enum type for `machine.status.phase` (controllers are not setting this value anymore) + +### ClusterClass + +- See changes that applies to [all kind](#all-kind) +- The `definitionFrom` field (deprecated since CAPI v1.8) has been removed from + - `cluster.spec.topology.variables` + - `cluster.spec.topology.controlPlane.variables.override` + - `cluster.spec.topology.workers[].machineDeployments.variables.override` +- 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 [dataSecretCreated](#cluster-api-contract-changes)). +- See changes that applies to [all kind](#all-kind) +- The `spec.useExperimentalRetryJoin` field (deprecated in CAPI v1.2!) has been removed. +- Informations about the initial provisioning process are now surfacing under `status.initialization` (see [dataSecretCreated](#cluster-api-contract-changes)). + - `status.ready` has beed 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 [dataSecretCreated](#cluster-api-contract-changes)). +- See changes that applies to [all kind](#all-kind) +- Replica counters are now consistent with replica counters from other resources (see [dataSecretCreated](#cluster-api-contract-changes)). + - `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 +- Informations about the initial provisioning process are now surfacing under `status.initialization` (see [dataSecretCreated](#cluster-api-contract-changes)). + - `status.ready` has beed dropped + - `status.initialized` has beed replaced by `status.initialization.controlPlaneInitialized` +- 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`. -### 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. - -### Deprecation +- 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 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 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. + +### 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 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 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,26 +278,56 @@ See [provider contracts](../contracts/overview.md) for more details. - `MachinePoolPhase`, used in `machinePool.status.phase` - `MachinePhase`, used in `machine.status.phase` -### Removals +## Removals 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: +However, as documented in [Suggested changes for providers](#suggested-changes-for-providers), it is highly reccomanded 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 package, the code handling 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 + +- We highly recommend providers to start using to Cluster API v1beta2 types when bumping to CAPI v1.11. + This requires changing following import: + + ```go + import ( + ... + clusterv1 "sigs.k8s.io/cluster-api/api/v1beta1" + ) + ``` + + into: + + ```go + import ( + ... + clusterv1 "sigs.k8s.io/cluster-api/api/v1beta2" + ) + ``` -### Suggested changes for providers + 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 recommanded (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, we highly recommend providers to check new + conditions instad of old ones. Utils for working with new conditions ara available in the `sigs.k8s.io/cluster-api/util/conditions`. - 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 +- Depending on which option you are choosing for the Cluster API contract your are going to implement, 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; 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 @@ -120,22 +335,21 @@ As documented in [Suggested changes for providers](#suggested-changes-for-provid - 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 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, 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 +361,127 @@ 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 , 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 +it is require 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 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. -#### How to implement the new v1beta2 contract +### How to start using metav1.conditions -We highly recommend providers to start planning the move to the new v1beta2 version of the Cluster API contract as soon -as possible. +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. -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. +As a quick summary, transition should go trough following phases: -#### How to start using metav1.conditions +#### Stage 1 -We highly recommend providers define their future strategy for condition management as soon as possible. +Add `status.v1beta2.conditions` to your API (existing conditions will remain at `status.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 about how to implement a phased transition. +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 object in this phase. + +Important! +All package below `sigs.k8s.io/cluster-api/util/deprecated/` 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 `clusterv1beta1.Conditions` in `status.deprecated.v1beta1.conditions` +- the `patch` package provides access to utils for patching object in this phase + +Important! +All package below `sigs.k8s.io/cluster-api/util/deprecated/` are 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 object in this phase From 4d40850a0dc6922c12937effd88174b1671b09b1 Mon Sep 17 00:00:00 2001 From: fabriziopandini Date: Mon, 19 May 2025 13:03:11 +0200 Subject: [PATCH 2/8] Fix go version --- .../book/src/developer/providers/migrations/v1.10-to-v1.11.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 4d4678121728..5a6a95574640 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 @@ -43,8 +43,8 @@ proposal because most of the changes described below are a consequence of the wo ## Go version -- The minimal Go version required to build Cluster API is v1.23.x -- The Go version used by Cluster API is v1.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 From e6f3f6de1bc62ae44567d40b3d3871ec142b868c Mon Sep 17 00:00:00 2001 From: fabriziopandini Date: Mon, 19 May 2025 18:33:47 +0200 Subject: [PATCH 3/8] Address comments --- .../providers/migrations/v1.10-to-v1.11.md | 153 ++++++++---------- 1 file changed, 69 insertions(+), 84 deletions(-) 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 5a6a95574640..21ae1f1dafc3 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 @@ -13,7 +13,7 @@ proposal because most of the changes described below are a consequence of the wo * [Go version](#go-version) * [Dependencies](#dependencies) * [API Changes](#api-changes) - * [All Kind](#all-kind) + * [All CRDs](#all-crds) * [Cluster](#cluster) * [MachineDeployment](#machinedeployment) * [MachineSet](#machineset) @@ -30,7 +30,7 @@ proposal because most of the changes described below are a consequence of the wo * [Contract rules for IPAM provider](#contract-rules-for-ipam-provider) * [Contract rules for MachinePool](#contract-rules-for-machinepool) * [Deprecations](#deprecations) - * [Removals](#removals) + * [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) @@ -59,7 +59,7 @@ proposal because most of the changes described below are a consequence of the wo - `ExtensionConfig` v1alpha1 has been deprecated, and it will be removed in a following release. - `ExtensionConfig` v1beta2 has created (thus aligning with other Cluster API resources) - ### All Kind + ### 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: @@ -70,103 +70,95 @@ proposal because most of the changes described below are a consequence of the wo ### Cluster -- See changes that applies to [all kind](#all-kind) -- The `spec.topology.class` has been renamed to `spec.topology.classRef.name` -- The `spec.topology.classNamespace` has been renamed to `spec.topology.classRef.namespace` +- 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 - - `cluster.spec.topology.variables` - - `cluster.spec.topology.controlPlane.variables.override` - - `cluster.spec.topology.workers[].machineDeployments.variables.override` -- Informations about the initial provisioning process are now surfacing under `status.initialization` (see [dataSecretCreated](#cluster-api-contract-changes)). - - `status.infrastructureReady` has beed replaced by `status.initialization.infrastructureProvisioned` - - `status.controlPlaneReady` has beed replaced by `status.initialization.controlPlaneInitialized` -- Replica counters have been added to the cluster object - - `status.controlPlane` now reports replica counters surfaced from the control plane object (see [dataSecretCreated](#cluster-api-contract-changes)). + - `spec.topology.variables` + - `spec.topology.controlPlane.variables.overrides` + - `spec.topology.workers[].machineDeployments.variables.overrides` + - `spec.topology.workers[].machinePools.variables.overrides` +- Informations 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 (see [dataSecretCreated](#cluster-api-contract-changes)). +- 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 `cluster.status.phase` (controllers are not setting this value anymore) + - 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 applies to [all kind](#all-kind) +- 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 (see [dataSecretCreated](#cluster-api-contract-changes)). +- 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 `machineDeployment.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. - + - 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 applies to [all kind](#all-kind) -- Replica counters are now consistent with replica counters from other resources +- 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 (see [dataSecretCreated](#cluster-api-contract-changes)). +- 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 applies to [all kind](#all-kind) -- 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 (see [dataSecretCreated](#cluster-api-contract-changes)). +- 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 `machinePool.status.phase` (controllers are not setting this value anymore) + - 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 applies to [all kind](#all-kind) -- Informations about the initial provisioning process are now surfacing under `status.initialization` (see [dataSecretCreated](#cluster-api-contract-changes)). - - `status.infrastructureReady` has beed replaced by `status.initialization.infrastructureProvisioned` - - `status.bootstrapReady` has beed replaced by `status.initialization.bootstrapDataSecretCreated` -- Support for terminal errors has been dropped (see [dataSecretCreated](#cluster-api-contract-changes)). +- See changes that apply to [all CRDs](#all-crds) +- Information about the initial provisioning process is now surfacing under the new `status.initialization`. + - `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 `machine.status.phase` (controllers are not setting this value anymore) + - The const values for `Failed` phase has been deprecated in the enum type for `status.phase` (controllers are not setting this value anymore) ### ClusterClass -- See changes that applies to [all kind](#all-kind) -- The `definitionFrom` field (deprecated since CAPI v1.8) has been removed from - - `cluster.spec.topology.variables` - - `cluster.spec.topology.controlPlane.variables.override` - - `cluster.spec.topology.workers[].machineDeployments.variables.override` -- The `builtin.Cluster.Network.IPFamily` variable has been removed and it cannot be used anymore in patches +- See changes that apply to [all CRDs](#all-crds) +- 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 [dataSecretCreated](#cluster-api-contract-changes)). -- See changes that applies to [all kind](#all-kind) +- 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. -- Informations about the initial provisioning process are now surfacing under `status.initialization` (see [dataSecretCreated](#cluster-api-contract-changes)). - - `status.ready` has beed replaced by `status.initialization.dataSecretCreated` +- 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 [dataSecretCreated](#cluster-api-contract-changes)). -- See changes that applies to [all kind](#all-kind) -- Replica counters are now consistent with replica counters from other resources (see [dataSecretCreated](#cluster-api-contract-changes)). +- 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 -- Informations about the initial provisioning process are now surfacing under `status.initialization` (see [dataSecretCreated](#cluster-api-contract-changes)). - - `status.ready` has beed dropped - - `status.initialized` has beed replaced by `status.initialization.controlPlaneInitialized` -- Support for terminal errors has been dropped (see [dataSecretCreated](#cluster-api-contract-changes)). +- 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 @@ -175,8 +167,7 @@ proposal because most of the changes described below are a consequence of the wo - 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 some limitations; please - read details in following paragraphs: - - + 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). @@ -194,10 +185,8 @@ for providers still implementing the v1beta1 contract. - 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 Machine controller won't consider the presence of `status.failureReason` and `status.failureMessage` info + - The Cluster 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 InfraMachine @@ -243,10 +232,8 @@ for providers still implementing the v1beta1 contract. - 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 Machine controller won't consider the presence of `status.failureReason` and `status.failureMessage` info + - The Cluster 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 IPAM provider @@ -278,22 +265,20 @@ TODO - `MachinePoolPhase`, used in `machinePool.status.phase` - `MachinePhase`, used in `machine.status.phase` -## Removals - -There are no removals in the CAPI v1.11 version. +## Removals scheduled for future releases -However, as documented in [Suggested changes for providers](#suggested-changes-for-providers), it is highly reccomanded to start planning for future removals: +As documented in [Suggested changes for providers](#suggested-changes-for-providers), it is highly reccommanded 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/deprecated/v1beta1` package, - the `util/deprecated/v1beta1` package package, the code handling conditions in `util/patch.Helper` + 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 ## Suggested changes for providers -- We highly recommend providers to start using to Cluster API v1beta2 types when bumping to CAPI v1.11. +- We highly recommend providers to start using Cluster API v1beta2 types when bumping to CAPI v1.11. This requires changing following import: ```go @@ -317,14 +302,14 @@ However, as documented in [Suggested changes for providers](#suggested-changes-f Note: it is technically possible for providers to keep using v1beta1 types from CAPI v1.11, but this is not recommanded (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, we highly recommend providers to check new - conditions instad of old ones. Utils for working with new conditions ara available in the `sigs.k8s.io/cluster-api/util/conditions`. +- If providers are using Conditions from Cluster API resources, 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`. - 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 -- Depending on which option you are choosing for the Cluster API contract your are going to implement, please refer to: +- Depending on which Cluster API contract version you are choosing to implement, 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) @@ -337,7 +322,7 @@ However, as documented in [Suggested changes for providers](#suggested-changes-f 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 `util/deprecated/v1beta1` package, - the code handling conditions in `util/patch.Helper` and everything related to the custom Cluster API custom condition type. + 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, 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) @@ -372,7 +357,7 @@ 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 , It is also highly recommended to check the implementation of all the other rules +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. @@ -388,7 +373,7 @@ metadata: ### 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 -it is require to change following imports: +so it is required to change following imports: ```go import ( @@ -410,7 +395,7 @@ import ( 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 `util/deprecated/v1beta1` package, -the code handling conditions in `util/patch.Helper` and everything related to the custom Cluster API custom condition type. +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. @@ -419,7 +404,7 @@ See [Suggested changes for providers](#suggested-changes-for-providers) for more 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. -As a quick summary, transition should go trough following phases: +As a quick summary, transition should go through following phases: #### Stage 1 @@ -438,11 +423,11 @@ import ( - 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 object in this phase. +- the `patch` package alias provides access to utils for patching objects in this phase. -Important! -All package below `sigs.k8s.io/cluster-api/util/deprecated/` are going to be removed from CAPI when the -v1beta1 removal will happen (tentative Aug 2026). +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 @@ -462,8 +447,8 @@ import ( ``` - the `conditions` package provides access to utils for managing `metav1.Conditions` in `status.conditions` -- the `v1beta1conditions` package alias provides access to utils for managing `clusterv1beta1.Conditions` in `status.deprecated.v1beta1.conditions` -- the `patch` package provides access to utils for patching object in this phase +- 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! All package below `sigs.k8s.io/cluster-api/util/deprecated/` are going to be removed from CAPI when the @@ -484,4 +469,4 @@ import ( ``` - the `conditions` package provides access to utils for managing `metav1.Conditions` in `status.conditions` -- the `patch` package provides access to utils for patching object in this phase +- the `patch` package provides access to utils for patching objects in this phase From 24898cced0c844fc1ade695ba33749764bc94158 Mon Sep 17 00:00:00 2001 From: fabriziopandini Date: Mon, 19 May 2025 22:10:10 +0200 Subject: [PATCH 4/8] Document change in builtin variables from 12235 --- docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md | 2 ++ 1 file changed, 2 insertions(+) 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 21ae1f1dafc3..eaa37306ec32 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 @@ -134,6 +134,8 @@ proposal because most of the changes described below are a consequence of the wo ### ClusterClass - See changes that apply to [all CRDs](#all-crds) +- The `builtin.cluster.classRef.Name` and `builtin.cluster.classRef.Namespace` variables has 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 From 9b36d511f5c9ac106b691597321306e9f67a4d07 Mon Sep 17 00:00:00 2001 From: fabriziopandini Date: Tue, 20 May 2025 12:30:50 +0200 Subject: [PATCH 5/8] More comments --- .../providers/migrations/v1.10-to-v1.11.md | 46 ++++++++++++------- 1 file changed, 30 insertions(+), 16 deletions(-) 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 eaa37306ec32..0e42817d302e 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 @@ -78,7 +78,7 @@ proposal because most of the changes described below are a consequence of the wo - `spec.topology.controlPlane.variables.overrides` - `spec.topology.workers[].machineDeployments.variables.overrides` - `spec.topology.workers[].machinePools.variables.overrides` -- Informations about the initial provisioning process are now surfacing under the new `status.initialization` field. +- 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 @@ -124,7 +124,7 @@ proposal because most of the changes described below are a consequence of the wo ### Machine - See changes that apply to [all CRDs](#all-crds) -- Information about the initial provisioning process is now surfacing under the new `status.initialization`. +- 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. @@ -134,7 +134,7 @@ proposal because most of the changes described below are a consequence of the wo ### ClusterClass - See changes that apply to [all CRDs](#all-crds) -- The `builtin.cluster.classRef.Name` and `builtin.cluster.classRef.Namespace` variables has been added +- 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 @@ -269,7 +269,7 @@ TODO ## Removals scheduled for future releases -As documented in [Suggested changes for providers](#suggested-changes-for-providers), it is highly reccommanded to 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 @@ -304,20 +304,25 @@ As documented in [Suggested changes for providers](#suggested-changes-for-provid Note: it is technically possible for providers to keep using v1beta1 types from CAPI v1.11, but this is not recommanded (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, 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`. +- 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; - 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 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, please refer to: +- 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; 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 +- 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 @@ -326,7 +331,7 @@ As documented in [Suggested changes for providers](#suggested-changes-for-provid 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, please refer to: +- 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) @@ -399,7 +404,14 @@ Also, please note that starting from the CAPI release when v1beta1 removal will 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. + +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, + +See [Suggested changes for providers](#suggested-changes-for-providers) and [Cluster API Contract changes](#cluster-api-contract-changes) +for more details. ### How to start using metav1.conditions @@ -453,7 +465,7 @@ import ( - the `patch` package provides access to utils for patching objects in this phase Important! -All package below `sigs.k8s.io/cluster-api/util/deprecated/` are going to be removed from CAPI when the +The "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 @@ -472,3 +484,5 @@ import ( - 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 + +### How to start using a custom type for conditions From c8bd2b0758dd565805fca60a0a07ae94d911c85d Mon Sep 17 00:00:00 2001 From: fabriziopandini Date: Tue, 20 May 2025 14:53:55 +0200 Subject: [PATCH 6/8] Document 12245 --- .../providers/migrations/v1.10-to-v1.11.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) 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 0e42817d302e..22d703312895 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 @@ -78,6 +78,9 @@ proposal because most of the changes described below are a consequence of the wo - `spec.topology.controlPlane.variables.overrides` - `spec.topology.workers[].machineDeployments.variables.overrides` - `spec.topology.workers[].machinePools.variables.overrides` +- The `unhealthyConditions` field has been renamed to `spec.unhealthyNodeConditions` in following struct: + - `spec.topology.controlPlane` + - `spec.topology.workers[].machineDeployments` - 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` @@ -131,9 +134,17 @@ proposal because most of the changes described below are a consequence of the wo - `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 `spec.unhealthyNodeConditions` in following struct: + - `spec.controlPlane` + - `spec.workers[].machineDeployments` - 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 @@ -484,5 +495,3 @@ import ( - 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 - -### How to start using a custom type for conditions From 712a6c28237fa64a09b57bfc2bb01af75f4cfad3 Mon Sep 17 00:00:00 2001 From: fabriziopandini Date: Tue, 20 May 2025 16:24:53 +0200 Subject: [PATCH 7/8] More comments --- .../providers/migrations/v1.10-to-v1.11.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) 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 22d703312895..b90b7ada477d 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 @@ -57,7 +57,7 @@ proposal because most of the changes described below are a consequence of the wo - 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 created (thus aligning with other Cluster API resources) + - `ExtensionConfig` v1beta2 been has created (thus aligning with other Cluster API resources) ### All CRDs @@ -76,11 +76,11 @@ proposal because most of the changes described below are a consequence of the wo - 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 `spec.unhealthyNodeConditions` in following struct: - - `spec.topology.controlPlane` - - `spec.topology.workers[].machineDeployments` + - `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` @@ -142,9 +142,9 @@ proposal because most of the changes described below are a consequence of the wo ### ClusterClass - See changes that apply to [all CRDs](#all-crds) -- The `unhealthyConditions` field has been renamed to `spec.unhealthyNodeConditions` in following struct: - - `spec.controlPlane` - - `spec.workers[].machineDeployments` +- 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 @@ -179,7 +179,7 @@ proposal because most of the changes described below are a consequence of the wo - 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 some limitations; please + - 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 @@ -476,7 +476,7 @@ import ( - the `patch` package provides access to utils for patching objects in this phase Important! -The "sigs.k8s.io/cluster-api/util/conditions/deprecated/v1beta1" is going to be removed from CAPI when the +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 From 9dd995ed9d8b11d2c549f0cd02108a9df354806f Mon Sep 17 00:00:00 2001 From: fabriziopandini Date: Tue, 20 May 2025 17:20:37 +0200 Subject: [PATCH 8/8] More comments --- .../src/developer/providers/migrations/v1.10-to-v1.11.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) 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 b90b7ada477d..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 @@ -19,6 +19,7 @@ proposal because most of the changes described below are a consequence of the wo * [MachineSet](#machineset) * [MachinePool](#machinepool) * [Machine](#machine) + * [MachineHealthCheck](#machinehealthcheck) * [ClusterClass](#clusterclass) * [KubeadmConfig](#kubeadmconfig) * [KubeadmControlPlane](#kubeadmcontrolplane) @@ -57,9 +58,9 @@ proposal because most of the changes described below are a consequence of the wo - 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 been has created (thus aligning with other Cluster API resources) + - `ExtensionConfig` v1beta2 has been created (thus aligning with other Cluster API resources) - ### All CRDs +### 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: @@ -313,7 +314,7 @@ As documented in [Suggested changes for providers](#suggested-changes-for-provid 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 recommanded (this approach was not tested during the implementation, we don't know if there are road blockers). + 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.