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/utilsGo module, released with the same version assigs.k8s.io/cluster-api; see the Code organization proposal for the guarantees of this module.
Graduation
- Both the
PriorityQueueand theReconcilerRateLimitingfeature gate graduated to GA - The
ClusterTopologyfeature gate graduated to Beta and is now enabled by default - The
MachineTaintPropagationfeature gate graduated to Beta and is now enabled by default
Implemented proposal
- 20260706-worker-version-pinning.md implementation started, not yet completed.
- Code organization: the Runtime SDK packages have been reorganized, see Go packages moved.
API Changes
Cluster
- The new
spec.topology.workers.machineDeployments[].versionandspec.topology.workers.machinePools[].versionfields have been added- NOTE: those field are part of the work for 20260706-worker-version-pinning.md, not yet completed.
- The new
spec.topology.controlPlane.healthCheck.checks.unhealthyExpressionsandspec.topology.workers.machineDeployments[].healthCheck.checks.unhealthyExpressionsfields have been added
MachineDeployment
- The new
WaitingForRolloutDecisionandRolloutBlockedreasons have been added for theRollingOutcondition
MachinePool
- The new
MachinesUpToDatecondition has been added
Machine
- The new
InPlaceUpdateBlockedandInternalErrorreasons have been added for theUpdatingcondition - The new
status.deletion.nodeDeletionStartTimefield has been addedspec.deletion.nodeDeletionTimeoutSecondsis now measured fromstatus.deletion.nodeDeletionStartTimeinstead of the Machine’sdeletionTimestamp; the same applies to the corresponding fields in Cluster topology, ClusterClass, KubeadmControlPlane and KubeadmControlPlaneTemplate
MachineHealthCheck
- The new
spec.checks.unhealthyExpressionsfield 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.templateandspec.workers.machinePools[].infrastructure.templatefields have been added- The existing
templateReffields are now optional; eithertemplateRefortemplatemust be set, but not both
- The existing
- The new
spec.controlPlane.healthCheck.checks.unhealthyExpressionsandspec.workers.machineDeployments[].healthCheck.checks.unhealthyExpressionsfields have been added
KubeadmConfig
- The new
spec.files[].deferfield has been added
KubeadmConfigTemplate
- KubeadmConfigTemplate
spec.template.spechas been aligned to changes in the KubeadmConfigspecstruct
KubeadmControlPlane
- KubeadmControlPlane
spec.kubeadmConfigSpechas been aligned to changes in the KubeadmConfigspecstruct - The new
WaitingForRolloutDecision,RolloutBlockedandInternalErrorreasons have been added for theRollingOutcondition
KubeadmControlPlaneTemplate
- KubeadmControlPlaneTemplate
spec.template.spechas been aligned to changes in the KubeadmControlPlanespecstruct
Runtime hooks Changes
- The
DiscoveryRequesthook message now embedsCommonRequest, i.e. thesettingsdefined in the ExtensionConfig are now also sent to the Discovery hook - The
CanUpdateMachineResponseandCanUpdateMachineSetResponsehook messages now embedCommonRetryResponseinstead ofCommonResponse;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
affectsAvailabilityfield has been added to theCanUpdateMachineResponseandCanUpdateMachineSetResponsehook messages; if not set, in-place updates are considered to affect the availability of the Machines - The new
allowedOperationsfield has been added to theCanUpdateMachineResponseandCanUpdateMachineSetResponsehook messages; it defines the operations (UpdateInPlace,Replace) Cluster API is allowed to use to roll out changes to the Machines- If not set, both
UpdateInPlaceandReplaceare allowed - If set to an empty list, no operation is allowed and the rollout is blocked
- If not set, both
- The new
updateStatusfield has been added to theUpdateMachineResponsehook message, with valuesInProgress,Failed,Blocked,CompletedandCompletedButDirty- If not set,
updateStatusis defaulted toInProgressifretryAfterSeconds> 0, and toCompletedotherwise (same behavior as before) InProgress,FailedandBlockedare retried afterretryAfterSeconds(a default of 5 minutes is used ifretryAfterSecondsis 0)CompletedButDirtycompletes the update, but the Machine is tracked as dirty until the next in-place update completes withCompletedstatusFailureis now considered an unexpected error and the hook is retried with exponential backoff
- If not set,
Cluster API Contract changes
- InfraMachinePool contract: the MachinePool controller now reads initialization completed from
status.initialization.provisionedas defined by the v1beta2 contract. For InfraMachinePool resources implementing the v1beta2 contract, Cluster API falls back tostatus.readyifstatus.initialization.provisionedis not set; this fallback is deprecated and will be removed in a future version of the contract.
Deprecation
- Both the
PriorityQueueandReconcilerRateLimitingfeatures are now GA so their corresponding feature gates are deprecated and will be removed in the v1.17 release. - The
MachineDeploymentTopologyFinalizerandMachineSetTopologyFinalizerconstants (in thev1beta2API package) are deprecated, because the finalizers are not set anymore (see Removals). - Handling of
status.readyfor InfraMachinePool resources implementing the v1beta2 contract is deprecated, providers should report initialization completed usingstatus.initialization.provisioned(see Cluster API Contract changes).
Removals
- The deprecated GA feature gate
MachineWaitForVolumeDetachConsiderVolumeAttachmentshas been removed - The following functions and types have been removed, please use ClusterCache or inline them instead:
controllers/remote.NewClusterClientcontrollers/remote.RESTConfigcontrollers/remote.ClusterClientGettercontrollers/remote/fake.NewClusterClient
- The deprecated
util/predicates.ClusterCreateInfraProvisionedandutil/predicates.ClusterUnpausedAndInfrastructureProvisionedpredicates have been removed, please useutil/predicates.ClusterPausedTransitionsOrInfrastructureProvisionedinstead. - The cleanup of the
controlplane.cluster.x-k8s.io/kubeadm-cluster-configurationMachine 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-historyannotation is not managed by the MachineDeployment controller anymore. - The
util/recordpackage 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.ioandmachineset.topology.cluster.x-k8s.iofinalizers 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/machinedeploymentandtopology/machinesetcontrollers don’t exist anymore, e.g. controller-runtime metrics and logs are now only reported for themachinedeploymentandmachinesetcontrollers. framework.CoreFinalizersAssertionWithClassyClustersnow expects the same finalizers asframework.CoreFinalizersAssertionWithLegacyClusters.
- Topology-owned MachineDeployments and MachineSets don’t get the
Go packages moved
The following packages have been moved as part of the Code organization proposal; update the import paths accordingly.
| Old package | New package | Notes |
|---|---|---|
sigs.k8s.io/cluster-api/exp/runtime/client | sigs.k8s.io/cluster-api/pkg/runtimesdk/client | The package now also contains the client implementation |
sigs.k8s.io/cluster-api/exp/runtime/server | sigs.k8s.io/cluster-api/utils/runtimesdk/server | The package is now in the sigs.k8s.io/cluster-api/utils Go module |
sigs.k8s.io/cluster-api/exp/runtime/topologymutation | sigs.k8s.io/cluster-api/pkg/runtimesdk/server/topologymutation | |
sigs.k8s.io/cluster-api/feature | sigs.k8s.io/cluster-api/pkg/features | The 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.readyfor InfraMachinePool resources implementing the v1beta2 contract is deprecated, providers should report initialization completed usingstatus.initialization.provisioned(see Cluster API Contract changes). - Runtime Extension implementers should import
sigs.k8s.io/cluster-api/utils/runtimesdk/serverfrom thesigs.k8s.io/cluster-api/utilsGo module instead ofsigs.k8s.io/cluster-api/exp/runtime/server. - Runtime Extension implementers should import
sigs.k8s.io/cluster-api/pkg/runtimesdk/server/topologymutationinstead ofsigs.k8s.io/cluster-api/exp/runtime/topologymutation; please note that this package is in thesigs.k8s.io/cluster-apiGo module, which offers only limited guarantees (see the Code organization proposal). test/framework.ResolveArtifactsDirectorynow defaults to_output/artifacts(instead of_artifacts) when neither an input nor theARTIFACTSenvironment variable is set; providers relying on this default should update their scripts and.gitignoreaccordingly.- Tilt now writes the binaries of all the providers to
_output/tilt/<provider name>in the Cluster API repository (instead of.tiltbuild/binin the provider repository); providers can drop.tiltbuildfrom 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/v1beta1package, theutil/deprecated/v1beta1package, the code handling old conditions inutil/patch.Helperand everything related to the custom Cluster API custom condition type. - All the
status.deprecatedfields 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