Cluster API v1.12 compared to v1.13

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

Any feedback or contributions to improve following documentation is welcome!

Go version

  • The minimal Go version required to build Cluster API is v1.24.x
  • The Go version used by Cluster API is v1.24.x

Dependencies

  • The Controller Runtime version used by Cluster API is v0.22.x
  • The version of the Kubernetes libraries used by Cluster API is v1.34.x

Graduation

  • Both the PriorityQueue and the ReconcilerRateLimiting feature gate graduated to beta and are enabled by default
    • Starting from this release ReconcilerRateLimiting feature also requires PriorityQueue to be enabled.
    • The same constraint has been backported on the CAPI 1.12 branch starting from v1.12.4 in order to ensure that ReconcilerRateLimiting works consistently with controller runtime exponential backoff.

Implemented proposal

The following proposal have been implemented in the Cluster API v1.12 release:

API Changes

Cluster

  • The new spec.topology.controlPlane.rollout.taints, spec.topology.workers.machineDeployments[].taints and spec.topology.workers.machinePools[].taints fields has been added
  • The new spec.topology.controlPlane.rollout.after and spec.topology.workers.machineDeployments[].rollout.after fields has been added

Machine

  • The new status.failureDomain field has been added.
  • The new NodeKubeadmLabelsAndTaintsSet condition has been added for Machines managed by KCP

ClusterClass

  • The new spec.controlPlane.rollout.taints, spec.workers.machineDeployments[].taints and spec.workers.machinePools[].taints fields has been added

KubeadmConfig

  • The new spec.diskSetup.partitions.diskLayout field has been added

KubeadmConfigTemplate

KubeadmConfigTemplate spec.template.spec has been aligned to changes in the KubeadmConfig spec struct

KubeadmControlPlane

  • The new spec.machineTemplate.taints field has been added
  • KubeadmControlPlane spec.kubeadmConfigSpec has been aligned to changes in the KubeadmConfig spec struct

KubeadmControlPlaneTemplate

  • KubeadmControlPlaneTemplate spec.template.spec has been aligned to changes in the KubeadmControlPlane spec struct

Runtime hooks Changes

  • Following hook messages are now using v1beta2 Cluster type instead of the deprecated v1beta1 Cluster type.

    • BeforeClusterCreateRequest
    • AfterControlPlaneInitializedRequest
    • BeforeClusterUpgradeRequest
    • BeforeControlPlaneUpgradeRequest
    • AfterControlPlaneUpgradeRequest
    • BeforeWorkersUpgradeRequest
    • AfterWorkersUpgradeRequest
    • AfterClusterUpgradeRequest
    • BeforeClusterDeleteRequest

  • The DiscoverVariablesResponse hook message are now using v1beta2 ClusterClassVariable type instead of the deprecated v1beta1 ClusterClassVariable type.

  • The Builtins type used for computing variables lists in the GeneratePatchesRequest and the ValidateTopologyRequest hook messages is now using a custom ObjectMeta type instead of the deprecated v1beta1 ObjectMeta type.

Cluster API Contract changes

  • A new, optional rule has been added to the bootstrap config contract and the infra machine provider contract, defining what is required for implementing support for in-place changes.
  • A new, optional rule has been added to the control plane contract, defining what is required for implementing support for taints.
  • A new, optional rule has been added to the control plane contract, defining what is required for implementing support for rolloutAfter.
  • Clarification about expectations about consistency between metadata.yaml versions and cluster.x-k8s.io/<version> label on provider’s CRDs has been added to the clusterctl contract and to contract for all the provider types.

Deprecation

The following API types are now deprecated (you should use corresponding Dev* API types)

  • DockerCluster and DockerClusterTemplate
  • DockerMachine and DockerMachineTemplate
  • DockerMachinePool and DockerMachinePoolTemplate

Removals

  • Remove deprecated --enable-crd-storage-version-migration flag for clusterctl upgrade and corresponding provider CRD storage version migration code
  • The deprecated --disable-grouping flag for clusterctl describe cluster has been removed.
  • The deprecated ClusterCache.GetClientCertificatePrivateKey method has been removed.
  • The deprecated --cluster-concurrency CABPK command-line flag has been removed
  • Remove deprecated util/topology.ShouldSkipImmutabilityChecks (use util/topology.IsDryRunRequest instead)
  • Removed deprecated util/version.ParseMajorMinorPatch (use semver.Parse instead)
  • Removed deprecated util/version.ParseMajorMinorPatchTolerant (use semver.ParseTolerant instead)

Suggested changes for providers

  • A new conversion.MarshalDataUnsafeNoCopy func was introduced. The difference to conversion.MarshalData is that it mutates the passed in source object before marshaling to avoid additional memory allocations. Usually this is fine because this func is used at the end of ConvertFrom methods. Accordingly, we recommend to start using this new func, except if it’s not safe in your circumstances.
  • If you are developing a control plane provider with support for machines, please consider adding spec.machineTemplate.spec.taints (see contract)
  • Cluster API bumped the default values of --kube-api-qps & --kube-api-burst to 100/200 in CAPI-13317. You might want to consider doing the same.

Removals scheduled for future releases

As documented in Suggested changes for providers, it is highly recommended to start planning for future removals:

  • v1beta1 API version will be removed tentatively in April 2027 (instead of the original August 2026)
  • Starting from the CAPI release when v1beta1 removal will happen, tentatively April 2027, the Cluster API project will remove the Cluster API condition type, the util/conditions/deprecated/v1beta1 package, the util/deprecated/v1beta1 package, the code handling old conditions in util/patch.Helper and everything related to the custom Cluster API custom condition type.
  • All the status.deprecated fields will be removed tentatively in April 2027.
  • Compatibility support for the v1beta1 version of the Cluster API contract will be removed tentatively in April 2027
  • Removal of Docker* API types will happen in a future version (as soon as possible)
    • NOTE: CAPD is considered a test provider, API deprecation guarantee do not apply