sigs.k8s.io/cluster-api@v1.7.1/docs/book/src/developer/providers/migrations/v1.4-to-v1.5.md (about)

     1  # Cluster API v1.4 compared to v1.5
     2  
     3  This document provides an overview over relevant changes between Cluster API v1.4 and v1.5 for
     4  maintainers of providers and consumers of our Go API.
     5  
     6  ## Go version
     7  
     8  - The Go version used by Cluster API is Go 1.20.x
     9  
    10  ## Dependencies
    11  
    12  **Note**: Only the most relevant dependencies are listed, `k8s.io/` and `ginkgo`/`gomega` dependencies in Cluster API are kept in sync with the versions used by `sigs.k8s.io/controller-runtime`.
    13  
    14  - sigs.k8s.io/kind: v0.17.x => v0.20.x
    15  - sigs.k8s.io/controller-runtime: v0.14.x => v0.15.x
    16  - sigs.k8s.io/controller-tools: v0.11.x => v0.12.x
    17  
    18  ## Changes by Kind
    19  
    20  ### Deprecation
    21  
    22  - API version`v1alpha4` is deprecated and CAPI will stop serving this version in v1.6.
    23  - `sigs.k8s.io/cluster-api/controllers/remote.DefaultIndexex` has been deprecated and will be removed in a future release. Please use `sigs.k8s.io/cluster-api/controllers/external.NodeProviderIDIndex` instead. This index should not be used as a default index and should only be used if a controller is using `index.NodeProviderIDField`.
    24  
    25  ### Removals
    26  
    27  - API version `v1alpha3` is not served in v1.5 (users can enable it manually in case they are lagging behind with deprecation cycles). Important: `v1alpha3` will be completely removed in 1.6.
    28  - The lazy restmapper feature gate was removed in controller-runtime and lazy restmapper is now the default restmapper. Accordingly the `EXP_LAZY_RESTMAPPER` feature gate was removed in Cluster API.
    29  
    30  ### API Changes
    31  
    32  - InfrastructureMachinePools now include an optional status field for `infrastructureMachineKind`. This allows infrastructure providers to support MachinePool Machines by having the InfraMachinePool set the `infrastructureMachineKind` to the kind of their InfrastructureMachines. The InfrastructureMachinePool will be responsible for creating InfrastructureMachines as the MachinePool is scaled up, and the MachinePool controller will create Machines for each InfrastructureMachine and set the ownerRef. The InfrastructureMachinePool will be responsible for deleting the Machines as the MachinePool is scaled down in order for the Machine deletion workflow to function properly. In addition, the InfrastructureMachines must also have the following labels set by the InfrastructureMachinePool: `cluster.x-k8s.io/cluster-name` and `cluster.x-k8s.io/pool-name`. The `MachinePoolNameLabel` must also be formatted with `capilabels.MustFormatValue()` so that it will not exceed character limits. See the [MachinePool Machines proposal](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20220209-machinepool-machines.md) for more details and the [CAPD implementation](https://github.com/kubernetes-sigs/cluster-api/pull/8842) for a reference.
    33  
    34  ### Other
    35  
    36  - clusterctl move is adding the new annotation `clusterctl.cluster.x-k8s.io/delete-for-move` before object deletion.
    37  - Providers running CAPI release-0.3 clusterctl upgrade tests should set `WorkloadKubernetesVersion` field to the maximum workload cluster kubernetes version supported by the old providers in `ClusterctlUpgradeSpecInput`. For more information, please see: https://github.com/kubernetes-sigs/cluster-api/pull/8518#issuecomment-1508064859
    38  - Introduced function `CollectInfrastructureLogs` at the `ClusterLogCollector` interface in `test/framework/cluster_proxy.go` to allow collecting infrastructure related logs during tests.
    39  - A `GetTypedConfigOwner` function has been added to the `sigs.k8s.io./cluster-api/bootstrap/util` package. It is equivalent to `GetConfigOwner` except that it uses the cached typed client instead of the uncached unstructured client, so `GetTypedConfigOwner` is expected to be more performant.
    40  - `ClusterToObjectsMapper` in `sigs.k8s.io./cluster-api/util` has been deprecated, please use `ClusterToTypedObjectsMapper` instead.
    41  - The generated `kubeconfig` by the Control Plane providers must be labelled with the key-value pair `cluster.x-k8s.io/cluster-name=${CLUSTER_NAME}`.
    42    This is required for the CAPI managers caches to store and retrieve them for the required operations.
    43  - When using custom certificates, the certificates must be labeled with the key-value pair `cluster.x-k8s.io/cluster-name=${CLUSTER_NAME}`.
    44    This is required for the CAPI managers caches to store and retrieve them for the required operations.
    45  
    46  ### Suggested changes for providers
    47  
    48  -
    49  
    50  ## Notes about the controller-runtime bump
    51  
    52  This section shares our learnings of bumping controller-runtime to v0.15 in core Cluster API. It highlights the most relevant changes and pitfalls
    53  for Cluster API providers. For the full list of changes please see the [controller-runtime release notes](https://github.com/kubernetes-sigs/controller-runtime/releases/tag/v0.15.0).
    54  
    55  * Webhooks can now also return warnings, this requires adding an additional `admission.Warnings` return parameter to all webhooks.
    56  * Manager options have been refactored and old fields have been deprecated.
    57  * Manager now has a builtin profiler server which can be enabled via `Options.PprofBindAddress`, this allows us to remove our profiler server.
    58  * Controller builder has been refactored, this requires small changes to our controller setup code.
    59  * The EventHandler interface has been modified to also take a context, which affects our mapping functions (e.g. `ClusterToInfrastructureMapFunc`).
    60  * Controller-runtime now uses a lazy restmapper per default, i.e. API groups and resources are only fetched when they are actually used.
    61    This should drastically reduce the amount of API calls in clusters with a lot of CRDs.
    62  * Some wait utils in `k8s.io/apimachinery/pkg/util/wait` have been deprecated. The migration is relatively straightforward except that passing in `0`
    63    as a timeout in `wait.PollUntilContextTimeout` is treated as a timeout with 0 seconds, in `wait.PollImmediateWithContext` it is interpreted as infinity.
    64  * The fake client has been improved to handle status properly. In tests that write the CRD status, the CRDs should be added to the fake client via `WithStatusSubresource`.
    65  * Ensure that the e2e test suite is setting a logger (e.g. via `ctrl.SetLogger(klog.Background())` in `TestE2E`. Otherwise logs are not visible and controller-runtime will print a warning.
    66  
    67  For reference, please see the [Bump to CR v0.15 PR](https://github.com/kubernetes-sigs/cluster-api/pull/8007) in core Cluster API.