Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Cluster API v1.14 compared to v1.15

This document provides an overview over relevant changes between Cluster API v1.14 and v1.15 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.26.x
  • The Go version used by Cluster API is v1.26.x

Dependencies

  • The Controller Runtime version used by Cluster API is v0.25.x
  • The version of the Kubernetes libraries used by Cluster API is v1.37.x
  • Cluster API now ships the sigs.k8s.io/cluster-api/utils Go module, released with the same version as sigs.k8s.io/cluster-api; see the Code organization proposal for the guarantees of this module.

Graduation

  • Both the PriorityQueue and the ReconcilerRateLimiting feature gate graduated to GA
  • The ClusterTopology feature gate graduated to Beta and is now enabled by default
  • The MachineTaintPropagation feature gate graduated to Beta and is now enabled by default

Implemented proposal

API Changes

Cluster

  • The new spec.topology.workers.machineDeployments[].version and spec.topology.workers.machinePools[].version fields have been added
  • The new spec.topology.controlPlane.healthCheck.checks.unhealthyExpressions and spec.topology.workers.machineDeployments[].healthCheck.checks.unhealthyExpressions fields have been added

MachineDeployment

  • The new WaitingForRolloutDecision and RolloutBlocked reasons have been added for the RollingOut condition

MachinePool

  • The new MachinesUpToDate condition has been added

Machine

  • The new InPlaceUpdateBlocked and InternalError reasons have been added for the Updating condition
  • The new status.deletion.nodeDeletionStartTime field has been added
    • spec.deletion.nodeDeletionTimeoutSeconds is now measured from status.deletion.nodeDeletionStartTime instead of the Machine’s deletionTimestamp; the same applies to the corresponding fields in Cluster topology, ClusterClass, KubeadmControlPlane and KubeadmControlPlaneTemplate

MachineHealthCheck

  • The new spec.checks.unhealthyExpressions field has been added

ClusterClass

  • The new spec.infrastructure.template, spec.controlPlane.template, spec.controlPlane.machineInfrastructure.template, spec.workers.machineDeployments[].bootstrap.template, spec.workers.machineDeployments[].infrastructure.template, spec.workers.machinePools[].bootstrap.template and spec.workers.machinePools[].infrastructure.template fields have been added
    • The existing templateRef fields are now optional; either templateRef or template must be set, but not both
  • The new spec.controlPlane.healthCheck.checks.unhealthyExpressions and spec.workers.machineDeployments[].healthCheck.checks.unhealthyExpressions fields have been added

KubeadmConfig

  • The new spec.files[].defer field has been added

KubeadmConfigTemplate

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

KubeadmControlPlane

  • KubeadmControlPlane spec.kubeadmConfigSpec has been aligned to changes in the KubeadmConfig spec struct
  • The new WaitingForRolloutDecision, RolloutBlocked and InternalError reasons have been added for the RollingOut condition

KubeadmControlPlaneTemplate

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

Runtime hooks Changes

  • The DiscoveryRequest hook message now embeds CommonRequest, i.e. the settings defined in the ExtensionConfig are now also sent to the Discovery hook
  • The CanUpdateMachineResponse and CanUpdateMachineSetResponse hook messages now embed CommonRetryResponse instead of CommonResponse; retryAfterSeconds > 0 can be used to signal that the decision is still in progress, and the rollout waits until the hook is called again
  • The new affectsAvailability field has been added to the CanUpdateMachineResponse and CanUpdateMachineSetResponse hook messages; if not set, in-place updates are considered to affect the availability of the Machines
  • The new allowedOperations field has been added to the CanUpdateMachineResponse and CanUpdateMachineSetResponse hook messages; it defines the operations (UpdateInPlace, Replace) Cluster API is allowed to use to roll out changes to the Machines
    • If not set, both UpdateInPlace and Replace are allowed
    • If set to an empty list, no operation is allowed and the rollout is blocked
  • The new updateStatus field has been added to the UpdateMachineResponse hook message, with values InProgress, Failed, Blocked, Completed and CompletedButDirty
    • If not set, updateStatus is defaulted to InProgress if retryAfterSeconds > 0, and to Completed otherwise (same behavior as before)
    • InProgress, Failed and Blocked are retried after retryAfterSeconds (a default of 5 minutes is used if retryAfterSeconds is 0)
    • CompletedButDirty completes the update, but the Machine is tracked as dirty until the next in-place update completes with Completed
    • status Failure is now considered an unexpected error and the hook is retried with exponential backoff

Cluster API Contract changes

  • InfraMachinePool contract: the MachinePool controller now reads initialization completed from status.initialization.provisioned as defined by the v1beta2 contract. For InfraMachinePool resources implementing the v1beta2 contract, Cluster API falls back to status.ready if status.initialization.provisioned is not set; this fallback is deprecated and will be removed in a future version of the contract.

Deprecation

  • Both the PriorityQueue and ReconcilerRateLimiting features are now GA so their corresponding feature gates are deprecated and will be removed in the v1.17 release.
  • The MachineDeploymentTopologyFinalizer and MachineSetTopologyFinalizer constants (in the v1beta2 API package) are deprecated, because the finalizers are not set anymore (see Removals).
  • Handling of status.ready for InfraMachinePool resources implementing the v1beta2 contract is deprecated, providers should report initialization completed using status.initialization.provisioned (see Cluster API Contract changes).

Removals

  • The deprecated GA feature gate MachineWaitForVolumeDetachConsiderVolumeAttachments has been removed
  • The following functions and types have been removed, please use ClusterCache or inline them instead:
    • controllers/remote.NewClusterClient
    • controllers/remote.RESTConfig
    • controllers/remote.ClusterClientGetter
    • controllers/remote/fake.NewClusterClient
  • The deprecated util/predicates.ClusterCreateInfraProvisioned and util/predicates.ClusterUnpausedAndInfrastructureProvisioned predicates have been removed, please use util/predicates.ClusterPausedTransitionsOrInfrastructureProvisioned instead.
  • The cleanup of the controlplane.cluster.x-k8s.io/kubeadm-cluster-configuration Machine annotation (set by KCP in Cluster API <= v1.11) has been removed, upgrades directly from Cluster API <= v1.11 are not supported anymore.
  • The deprecated machinedeployment.clusters.x-k8s.io/revision-history annotation is not managed by the MachineDeployment controller anymore.
  • The util/record package has been removed, please use controller runtime mgr.GetEventRecorderFor instead.
  • The topology MachineDeployment and MachineSet controllers have been merged into the MachineDeployment and MachineSet controllers:
    • Topology-owned MachineDeployments and MachineSets don’t get the machinedeployment.topology.cluster.x-k8s.io and machineset.topology.cluster.x-k8s.io finalizers anymore. If these finalizers are still set (e.g. because the objects were created with an older version of Cluster API), they are removed by the MachineDeployment and MachineSet controllers. The templates referenced by a topology-owned MachineDeployment or MachineSet (and the MachineHealthCheck of a topology-owned MachineDeployment) are now cleaned up by the MachineDeployment and MachineSet controllers.
    • The topology/machinedeployment and topology/machineset controllers don’t exist anymore, e.g. controller-runtime metrics and logs are now only reported for the machinedeployment and machineset controllers.
    • framework.CoreFinalizersAssertionWithClassyClusters now expects the same finalizers as framework.CoreFinalizersAssertionWithLegacyClusters.

Go packages moved

The following packages have been moved as part of the Code organization proposal; update the import paths accordingly.

Old packageNew packageNotes
sigs.k8s.io/cluster-api/exp/runtime/clientsigs.k8s.io/cluster-api/pkg/runtimesdk/clientThe package now also contains the client implementation
sigs.k8s.io/cluster-api/exp/runtime/serversigs.k8s.io/cluster-api/utils/runtimesdk/serverThe package is now in the sigs.k8s.io/cluster-api/utils Go module
sigs.k8s.io/cluster-api/exp/runtime/topologymutationsigs.k8s.io/cluster-api/pkg/runtimesdk/server/topologymutation
sigs.k8s.io/cluster-api/featuresigs.k8s.io/cluster-api/pkg/featuresThe package name changed from feature to features

The Runtime SDK implementation previously under internal/runtime and internal/hooks is now under pkg/runtimesdk (client, client/fake, registry, hooks, test).

GetVariableValue and IsNotFoundError have been moved from sigs.k8s.io/cluster-api/core/reconcilers/topology/cluster/patches/variables to sigs.k8s.io/cluster-api/pkg/runtimesdk/server/topologymutation.

Suggested changes for providers

  • Handling of status.ready for InfraMachinePool resources implementing the v1beta2 contract is deprecated, providers should report initialization completed using status.initialization.provisioned (see Cluster API Contract changes).
  • Runtime Extension implementers should import sigs.k8s.io/cluster-api/utils/runtimesdk/server from the sigs.k8s.io/cluster-api/utils Go module instead of sigs.k8s.io/cluster-api/exp/runtime/server.
  • Runtime Extension implementers should import sigs.k8s.io/cluster-api/pkg/runtimesdk/server/topologymutation instead of sigs.k8s.io/cluster-api/exp/runtime/topologymutation; please note that this package is in the sigs.k8s.io/cluster-api Go module, which offers only limited guarantees (see the Code organization proposal).
  • test/framework.ResolveArtifactsDirectory now defaults to _output/artifacts (instead of _artifacts) when neither an input nor the ARTIFACTS environment variable is set; providers relying on this default should update their scripts and .gitignore accordingly.
  • Tilt now writes the binaries of all the providers to _output/tilt/<provider name> in the Cluster API repository (instead of .tiltbuild/bin in the provider repository); providers can drop .tiltbuild from their .gitignore.

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