Cluster API v1.4 compared to v1.5

This document provides an overview over relevant changes between Cluster API v1.4 and v1.5 for maintainers of providers and consumers of our Go API.

Go version

  • The Go version used by Cluster API is Go 1.20.x


Note: Only the most relevant dependencies are listed, and ginkgo/gomega dependencies in Cluster API are kept in sync with the versions used by

  • v0.17.x => v0.19.x
  • v0.14.x => v0.15.x
  • v0.11.x => v0.12.x

Changes by Kind


  • API versionv1alpha4 is deprecated and CAPI will stop serving this version in v1.6.


  • 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.
  • 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.

API Changes


  • clusterctl move is adding the new annotation before object deletion.
  • 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:
  • Introduced function CollectInfrastructureLogs at the ClusterLogCollector interface in test/framework/cluster_proxy.go to allow collecting infrastructure related logs during tests.

Suggested changes for providers

Notes about the controller-runtime bump

This section shares our learnings of bumping controller-runtime to v0.15 in core Cluster API. It highlights the most relevant changes and pitfalls for Cluster API providers. For the full list of changes please see the controller-runtime release notes.

  • Webhooks can now also return warnings, this requires adding an additional admission.Warnings return parameter to all webhooks.
  • Manager options have been refactored and old fields have been deprecated.
  • Manager now has a builtin profiler server which can be enabled via Options.PprofBindAddress, this allows us to remove our profiler server.
  • Controller builder has been refactored, this requires small changes to our controller setup code.
  • The EventHandler interface has been modified to also take a context, which affects our mapping functions (e.g. ClusterToInfrastructureMapFunc).
  • Controller-runtime now uses a lazy restmapper per default, i.e. API groups and resources are only fetched when they are actually used. This should drastically reduce the amount of API calls in clusters with a lot of CRDs.
  • Some wait utils in have been deprecated. The migration is relatively straightforward except that passing in 0 as a timeout in wait.PollUntilContextTimeout is treated as a timeout with 0 seconds, in wait.PollImmediateWithContext it is interpreted as infinity.
  • 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.
  • 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.

For reference, please see the Bump to CR v0.15 PR in core Cluster API.