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 8492f2ecd1f8..1ac1590e47f4 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 @@ -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) @@ -368,6 +368,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: ``, 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.