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

Dependencies

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.

  • sigs.k8s.io/kind: v0.17.x => v0.20.x
  • sigs.k8s.io/controller-runtime: v0.14.x => v0.15.x
  • sigs.k8s.io/controller-tools: v0.11.x => v0.12.x

Changes by Kind

Deprecation

  • API versionv1alpha4 is deprecated and CAPI will stop serving this version in v1.6.
  • 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.

Removals

  • 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

  • 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 for more details and the CAPD implementation for a reference.

Other

  • clusterctl move is adding the new annotation clusterctl.cluster.x-k8s.io/delete-for-move 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: https://github.com/kubernetes-sigs/cluster-api/pull/8518#issuecomment-1508064859
  • Introduced function CollectInfrastructureLogs at the ClusterLogCollector interface in test/framework/cluster_proxy.go to allow collecting infrastructure related logs during tests.
  • 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.
  • ClusterToObjectsMapper in sigs.k8s.io./cluster-api/util has been deprecated, please use ClusterToTypedObjectsMapper instead.
  • The generated kubeconfig by the Control Plane providers must be labelled with the key-value pair cluster.x-k8s.io/cluster-name=${CLUSTER_NAME}. This is required for the CAPI managers caches to store and retrieve them for the required operations.

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 k8s.io/apimachinery/pkg/util/wait 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.