Cluster API v1.2 compared to v1.3

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

Minimum Go version

  • The Go version used by Cluster API is Go 1.19.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/controller-runtime: v0.12.x => v0.13.x
  • sigs.k8s.io/controller-tools: v0.9.x => v0.10.x
  • sigs.k8s.io/kind: v0.14.x => v0.18.x
  • k8s.io/*: v0.24.x => v0.25.x (derived from controller-runtime)
  • github.com/onsi/ginkgo: v1.x => v2.x (derived from controller-runtime)
  • k8s.io/kubectl: v0.24.x => 0.25.x
  • github.com/joelanford/go-apidiff: 0.4.0 => 0.5.0

Changes by Kind

Deprecation

  • sigs.k8s.io/cluster-api/controllers/external.CloneTemplate has been deprecated and will be removed in a future release. Please use sigs.k8s.io/cluster-api/controllers/external.CreateFromTemplate instead.
  • clusterctl init --list-images has been deprecated and will be removed in a future release. Please use clusterctl init list-images instead.
  • clusterctl backup has been deprecated. Please use clusterctl move --to-directory instead.
  • clusterctl restore has been deprecated. Please use clusterctl move --from-directory instead.
  • Client deprecates Backup and Restore. Please use Move.
  • ObjectMover deprecates Backup and Restore. Adds replacements functions ToDirectory and FromDirectory.

Removals

  • MachinesByCreationTimestamp type has been removed.
  • ClusterCacheReconciler.Log has been removed. Use the logger from the context instead.

API Changes

  • A new timeout nodeVolumeDetachTimeout has been introduced that defines how long the controller will spend on waiting for all volumes to be detached. The default value is 0, meaning that the volume can be detached without any time limitations.
  • A new annotation machine.cluster.x-k8s.io/exclude-wait-for-node-volume-detach has been introduced that allows explicitly skip the waiting for node volume detaching.
  • A new annotation "cluster.x-k8s.io/replicas-managed-by" has been introduced to indicate that a MachinePool’s replica enforcement is delegated to an external autoscaler (not managed by Cluster API). For more information see the documentation here.
  • The Path func in the sigs.k8s.io/cluster-api/cmd/clusterctl/client/repository.Overrider interface has been adjusted to also return an error.

Other

  • clusterctl now emits a warning for provider CRDs which don’t comply with the CRD naming conventions. This warning can be skipped for resources not referenced by Cluster API core resources via the clusterctl.cluster.x-k8s.io/skip-crd-name-preflight-check annotation. The contracts specify:

    The CRD name must have the format produced by sigs.k8s.io/cluster-api/util/contract.CalculateCRDName(Group, Kind)

  • The Kubernetes default registry has been changed from k8s.gcr.io to registry.k8s.io. Kubernetes image promotion currently publishes to both registries. Please consider publishing manifests which reference the controller images from the new registry (for reference Cluster API PR).
  • e2e tests are upgraded to use Ginkgo v2 (v2.5.0) and Gomega v1.22.1. Providers who use the test framework from this release will also need to upgrade, because Ginkgo v2 can’t be imported alongside v1. Please see the Ginkgo upgrade guide, and note:
  • Cluster API introduced new logging guidelines. All reconcilers in the core repository were updated to log the entire object hierarchy. It would be great if providers would be adjusted as well to make it possible to cross-reference log entries across providers (please see CAPD for an infra provider reference implementation).
  • The CreateLogFile function and CreateLogFileInput struct in the E2E test framework for clusterctl has been renamed to OpenLogFile and OpenLogFileInput because the function will now append to the logfile instead of truncating the content.
  • The Move function in E2E test framework for clusterctl has been modified to:
    • print the clusterctl move command including the arguments similar to Init.
    • log the output to the a clusterctl-move.log file at the subdirectory logs/<namespace>.
  • The self-hosted upgrade test now also upgrades the self-hosted cluster’s Kubernetes version by default. For that it requires the following variables to be set:
    • KUBERNETES_VERSION_UPGRADE_FROM
    • KUBERNETES_VERSION_UPGRADE_TO
    • ETCD_VERSION_UPGRADE_TO
    • COREDNS_VERSION_UPGRADE_TO The variable SkipUpgrade could be set to revert to the old behaviour by making use of the KUBERNETES_VERSION variable and skipping the Kubernetes upgrade.
  • cert-manager upgraded from v1.9.1 to v1.10.1.
  • Machine providerID is now being strictly checked for equality when compared against Kubernetes node providerID data. This is the expected criteria for correlating a Cluster API machine to its corresponding Kubernetes node, but historically this comparison was not strict, and instead compared only against the ID substring part of the full providerID string. Because different providers construct providerID strings differently, the ID substring is not uniformly defined and implemented across providers, and thus the existing providerID equality cannot guarantee the correct Machine-Node correlation. It is very unlikely that this new behavior will break existing providers, but FYI: if strict providerID equality will degrade expected behaviors, you may need to update your provider implementation prior to adopting Cluster API v1.3.
  • The default minimum TLS version in use by the webhook servers is 1.2.
  • OwnerReferences are now more strictly enforced for objects managed by Cluster API. Machines, Bootstrap configs, Infrastructure Machines and Secrets created by CAPI components now have strictly enforced controller owner references. This is not expected to require changes for providers.

Suggested changes for providers

  • Provider can expose the configuration of the TLS Options for the webhook server; it is recommended to use utility functions under the util/flags package to ensure consistency across CAPI and other providers.