Merge pull request #12266 from sbueringer/pr-crd-migrator-node

📖 Migration doc: Add CRD migrator reminder, add apiGroups to imports

Author: k8s-ci-robot

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

@@ -56,23 +56,23 @@ proposal because most of the changes described below are a consequence of the wo
 
 - APIs have been moved to the top-level `api` folder (https://github.com/kubernetes-sigs/cluster-api/pull/12262).
   If you keep using `v1alpha` / `v1beta1` APIs, imports have to be adjusted accordingly: 
-  - `sigs.k8s.io/cluster-api/bootstrap/kubeadm/api/v1beta1` => `sigs.k8s.io/cluster-api/api/bootstrap/kubeadm/v1beta1`
-  - `sigs.k8s.io/cluster-api/controlplane/kubeadm/api/v1beta1` => `sigs.k8s.io/cluster-api/api/controlplane/kubeadm/v1beta1`
-  - `sigs.k8s.io/cluster-api/api/v1beta1` => `sigs.k8s.io/cluster-api/api/core/v1beta1`
-  - `sigs.k8s.io/cluster-api/exp/api/v1beta1` => `sigs.k8s.io/cluster-api/api/core/v1beta1`
-  - `sigs.k8s.io/cluster-api/exp/ipam/api/v1alpha1` => `sigs.k8s.io/cluster-api/api/ipam/v1alpha1`
-  - `sigs.k8s.io/cluster-api/exp/ipam/api/v1beta1` => `sigs.k8s.io/cluster-api/api/ipam/v1beta1`
-  - `sigs.k8s.io/cluster-api/exp/runtime/api/v1alpha1` => `sigs.k8s.io/cluster-api/api/runtime/v1alpha1`
-  - `sigs.k8s.io/cluster-api/exp/runtime/hooks/api/v1alpha1` => `sigs.k8s.io/cluster-api/api/runtime/hooks/v1alpha1`
+  - `sigs.k8s.io/cluster-api/bootstrap/kubeadm/api/v1beta1` => `sigs.k8s.io/cluster-api/api/bootstrap/kubeadm/v1beta1` (apiGroup: `bootstrap.cluster.x-k8s.io`)
+  - `sigs.k8s.io/cluster-api/controlplane/kubeadm/api/v1beta1` => `sigs.k8s.io/cluster-api/api/controlplane/kubeadm/v1beta1` (apiGroup: `controlplane.cluster.x-k8s.io`)
+  - `sigs.k8s.io/cluster-api/api/v1beta1` => `sigs.k8s.io/cluster-api/api/core/v1beta1` (apiGroup: `cluster.x-k8s.io`)
+  - `sigs.k8s.io/cluster-api/exp/api/v1beta1` => `sigs.k8s.io/cluster-api/api/core/v1beta1` (apiGroup: `cluster.x-k8s.io`)
+  - `sigs.k8s.io/cluster-api/exp/ipam/api/v1alpha1` => `sigs.k8s.io/cluster-api/api/ipam/v1alpha1` (apiGroup: `ipam.cluster.x-k8s.io`)
+  - `sigs.k8s.io/cluster-api/exp/ipam/api/v1beta1` => `sigs.k8s.io/cluster-api/api/ipam/v1beta1` (apiGroup: `ipam.cluster.x-k8s.io`)
+  - `sigs.k8s.io/cluster-api/exp/runtime/api/v1alpha1` => `sigs.k8s.io/cluster-api/api/runtime/v1alpha1` (apiGroup: `runtime.cluster.x-k8s.io`)
+  - `sigs.k8s.io/cluster-api/exp/runtime/hooks/api/v1alpha1` => `sigs.k8s.io/cluster-api/api/runtime/hooks/v1alpha1` (apiGroup: `hooks.runtime.cluster.x-k8s.io`)
 - v1beta1 API version is now deprecated and it will be removed tentatively in August 2026
 - v1beta2 API version has been introduced; see following paragraphs for more details. The APIs have 
   been added in the following packages:
-  - `sigs.k8s.io/cluster-api/api/bootstrap/kubeadm/v1beta2`
-  - `sigs.k8s.io/cluster-api/api/controlplane/kubeadm/v1beta2`
-  - `sigs.k8s.io/cluster-api/api/addons/v1beta2`
-  - `sigs.k8s.io/cluster-api/api/core/v1beta2`
-  - `sigs.k8s.io/cluster-api/api/ipam/v1beta2`
-  - `sigs.k8s.io/cluster-api/api/runtime/v1beta2`
+  - `sigs.k8s.io/cluster-api/api/bootstrap/kubeadm/v1beta2` (apiGroup: `bootstrap.cluster.x-k8s.io`)
+  - `sigs.k8s.io/cluster-api/api/controlplane/kubeadm/v1beta2` (apiGroup: `controlplane.cluster.x-k8s.io`)
+  - `sigs.k8s.io/cluster-api/api/addons/v1beta2` (apiGroup: `addons.cluster.x-k8s.io`)
+  - `sigs.k8s.io/cluster-api/api/core/v1beta2` (apiGroup: `cluster.x-k8s.io`)
+  - `sigs.k8s.io/cluster-api/api/ipam/v1beta2` (apiGroup: `ipam.cluster.x-k8s.io`)
+  - `sigs.k8s.io/cluster-api/api/runtime/v1beta2` (apiGroup: `runtime.cluster.x-k8s.io`)
 - 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)
@@ -388,6 +388,21 @@ As documented in [Suggested changes for providers](#suggested-changes-for-provid
   * [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)
 
+- core Cluster API added the new CRD migrator component in the v1.9 release. For more details, see: https://github.com/kubernetes-sigs/cluster-api/issues/11894
+  - CRD migration in clusterctl has been deprecated and will be removed in CAPI v1.13, so it's recommended to
+    adopt the CRD migrator in providers instead.
+  - Please see the examples in https://github.com/kubernetes-sigs/cluster-api/pull/11889, the following high-level steps are required:
+    - Add the `--skip-crd-migration-phases` command-line flag that allows to skip CRD migration phases
+    - Setup the `CRDMigrator` component with the manager.
+    - Configure all CRDs owned by your provider, only set `UseCache` for the objects for which your provider already has an informer.
+    - Add the following RBAC:
+    - resources: `customresourcedefinitions`, verbs: `get;list;watch`
+    - resources: `customresourcedefinitions;customresourcedefinitions/status`, resourceNames: `<crd-name>`, verbs: `update;patch`
+      - Note: The CRD migrator will add the `crd-migration.cluster.x-k8s.io/observed-generation` annotation on the CRD object,
+        please ensure that if these CRD objects are deployed with a tool like kapp / Argo / Flux the annotation is not continuously removed.
+    - For all CRs that should be migrated by the `CRDMigrator`: verbs: `get;list;watch;patch;update`
+    - For all CRs with `UseStatusForStorageVersionMigration: true` verbs: `update;patch` on their `/status` resource (e.g. `ipaddressclaims/status`)
+
 ### 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.