Merge pull request #12571 from sbueringer/pr-improve-migration-doc

📖 Improve v1.10-to-v1.11 migration doc

Author: k8s-ci-robot

docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md

@@ -1,7 +1,12 @@
 # Cluster API v1.10 compared to v1.11
 
 This document provides an overview over relevant changes between Cluster API v1.10 and v1.11 for
-maintainers of providers and consumers of our Go API.
+all Cluster API users. The document has the following sections:
+* A detailed list about [API changes](#api-changes) and [contract changes](#cluster-api-contract-changes)
+* Recommendations for different kind of CAPI users:
+  * [Recommendation for everyone](#recommendation-for-everyone)
+  * [Suggested changes for clients using Cluster API Go types](#suggested-changes-for-clients-using-cluster-api-go-types)
+  * [Suggested changes for providers](#suggested-changes-for-providers)
 
 Any feedback or contributions to improve following documentation is welcome!
 
@@ -41,6 +46,8 @@ proposal because most of the changes described below are a consequence of the wo
   * [Deprecations](#deprecations)
   * [clusterctl changes](#clusterctl-changes)
   * [Removals scheduled for future releases](#removals-scheduled-for-future-releases)
+  * [Recommendation for everyone](#recommendation-for-everyone)
+  * [Suggested changes for clients using Cluster API Go types](#suggested-changes-for-clients-using-cluster-api-go-types)
   * [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)
@@ -110,7 +117,9 @@ When looking at API changes introduced in the v1beta2 API version for each CRD i
   - Additionally, fields inferred from top level objects have been removed, thus getting rid of a common source of confusion/issues.
 - Compliance with K8s API guidelines:
   - Thanks to the adoption of the [KAL linter](https://github.com/kubernetes-sigs/kube-api-linter) compliance with K8s API guidelines has been greatly improved.
-  - All Duration fields are now represented as `*int32` fields with units being part of the field name.
+  - All `metav1.Duration` fields (e.g. `nodeDeletionTimeout`) are now represented as `*int32` fields with units being part of the field name (e.g. `nodeDeletionTimeoutSeconds`).
+    - A side effect of this is that if durations were specified on a sub-second granularity conversion will truncate to seconds.
+      E.g. this means if you apply a v1beta1 object with `nodeDeletionTimeout: 1s5ms` only `1s` will be stored and returned on reads.
   - All `bool` fields have been changed to `*bool` to preserve user intent.
   - Extensive work has been done to ensure `required` and `optional` is explicitly set in the API, and that
     both serialization and validation works accordingly:
@@ -2711,7 +2720,14 @@ As documented in [Suggested changes for providers](#suggested-changes-for-provid
   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
+## Recommendation for everyone
+
+- As a general recommendation we suggest to upgrade first to CAPI v1.10 before moving to CAPI v1.11 / v1beta2.
+  - v1.10 introduced additional field validation on API fields.
+  - Upgrading to v1.10 allows you to first address potential issues with existing invalid field values
+    before picking up CAPI v1.11 / v1beta2, which will start converting v1beta1 objects to v1beta2 objects.
+
+## Suggested changes for clients using Cluster API Go types
 
 - We highly recommend providers to start using Cluster API v1beta2 types when bumping to CAPI v1.11.
   This requires changing following import:
@@ -2744,7 +2760,37 @@ As documented in [Suggested changes for providers](#suggested-changes-for-provid
   Last but not least, please be aware that given the issues above, this approach was not tested during the implementation,
   and 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
+- If you are using Conditions from Cluster API resources, e.g. by looking at the `ControlPlaneInitialized` condition
+  on the Cluster object, we highly recommend clients 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.
+
+- References on Cluster, KubeadmControlPlane, MachineDeployment, MachinePool, MachineSet and Machine are now using the
+  `ContractVersionedObjectReference` type instead of `corev1.ObjectReference`. These references can now be resolved with
+  `external.GetObjectFromContractVersionedRef` instead of `external.Get`:
+
+  ```go
+  external.GetObjectFromContractVersionedRef(ctx, r.Client, cluster.Spec.InfrastructureRef, cluster.Namespace)
+  ```
+
+- Go clients writing status of core Cluster API objects, should use at least Cluster API v1.9 Go types.
+  If that is not possible, avoid updating or patching the entire status field and instead you should patch only individual fields.
+  (Cluster API v1.9 introduced `.status.v1beta2` fields that are necessary for lossless v1beta2 => v1beta1 => v1beta2 round trips)
+
+- Important! Please pay attention to field removals, e.g. if you are using Go types to write object, either migrate to v1beta2 or make sure
+  to stop setting the removed fields. The removed fields won't be preserved even if setting them via v1beta1 Go types.
+
+- All `metav1.Duration` fields (e.g. `nodeDeletionTimeout`) are now represented as `*int32` fields with units being part of the field name (e.g. `nodeDeletionTimeoutSeconds`).
+  - A side effect of this is that if durations were specified on a sub-second granularity conversion will truncate to seconds.
+    E.g. this means if you apply a v1beta1 object with `nodeDeletionTimeout: 1s5ms` only `1s` will be stored and returned on reads.
+
+## Suggested changes for providers
+
+- All recommendations in [Suggested changes for clients using Cluster API Go types](#suggested-changes-for-clients-using-cluster-api-go-types) also apply to providers.
+
+- 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`
@@ -2823,10 +2869,12 @@ Please see [Cluster API Contract changes](#cluster-api-contract-changes) and [pr
 We highly recommend providers to start planning the move to the new v1beta2 version of the Cluster API contract as soon
 as possible.
 
-Implementing the new v1beta2 contract for providers is a two step operation:
+Implementing the new v1beta2 contract for providers is a multistep 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.
+  - If providers are starting to use `api/core/v1beta2/clusterv1.ObjectMeta` in your API types,
+    please note that it is necessary to set the `omitzero` JSON marker
 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.