Cluster API v1.13 compared to v1.14

This document provides an overview over relevant changes between Cluster API v1.13 and v1.14 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.24.x
  • The version of the Kubernetes libraries used by Cluster API is v1.36.x

Graduation

  • No feature flags has been graduated in this release

Implemented proposal

API Changes

Cluster

  • The new status.controlPlane.versions and status.workers.versions fields has been added
  • The new status.controlPlane.upgradePlan and status.workers.upgradePlan fields has been added

MachineDeployment

  • The new status.versions field has been added

MachineSet

  • The new status.versions field has been added

MachinePool

  • The new status.versions field has been added

Machine

  • The new status.deletion.waitForPreDrainHookStartTime and status.deletion.waitForPreTerminateHookStartTime fields has been added

KubeadmConfig

  • The new spec.files[].contentFormat 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 status.versions field has been added, the existing status.version has been deprecated

KubeadmControlPlaneTemplate

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

Runtime hooks Changes

  • Please note that since CAPI-13813 errors returned from Runtime Extensions might be surfaced in conditions. Accordingly, please ensure that the error messages are deterministic to avoid infinite reconciles. This change was done because we realized that errors reported by Runtime Extensions are a crucial feedback mechanism to users and its too cumbersome for users to search in controller logs for errors.

Cluster API Contract changes

  • All contracts: document necessary RBAC rules for enabling usage of the OwnerReferencesPermissionEnforcement admission controller.
  • Control plane contract:
    • Introduce optional contract field status.versions for control plane providers which allows control of the version.
    • The optional contract field status.version has been deprecated

Deprecation

  • Control plane contract:
    • The optional contract field status.version has been deprecated; the new optional contract field status.versions must be used instead.
  • The following functions and types have been deprecated, please use ClusterCache or inline them instead:
    • controllers/remote.NewClusterClient
    • controllers/remote.RESTConfig
    • controllers/remote.ClusterClientGetter
    • controllers/remote/fake.NewClusterClient
  • The util/record package has been deprecated, please use controller runtime mgr.GetEventRecorderFor instead.

Removals

  • No removal in this release

Suggested changes for providers

  • Providers implementers should read the code organization proposal and take into account:
    • Different level of guarantees provided by different go modules
    • New guidelines for bumping go versions
  • It is highly recommended to start planning for future removals described in following paragraphs

Removals scheduled for future releases

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

Important:

  • The v1beta1 API version in core Cluster API, CABPK and KCP is on track to be unserved in CAPI v1.16. All the consumers of this API version should migrate to v1beta2 ASAP.
    • Utils for the Cluster API v1beta1 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 will be removed as a next step.
    • All the status.deprecated fields existing in v1beta2 types (used for v1beta1 down conversions) types will be removed as a next step.
  • Support for the Cluster API v1beta1 contract versions is on track to be dropped in CAPI v1.16. Provider should start implementing the v1beta2 contract ASAP.
  • Removal of Docker* API resources will happen in CAPI v1.15. All the consumers of these API resources should migrate to Dev* API resources ASAP.