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
Note: Only the most relevant dependencies are listed,
in Cluster API are kept in sync with the versions used by
- 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
sigs.k8s.io/cluster-api/controllers/external.CloneTemplatehas been deprecated and will be removed in a future release. Please use
clusterctl init --list-imageshas been deprecated and will be removed in a future release. Please use
clusterctl init list-imagesinstead.
clusterctl backuphas been deprecated. Please use
clusterctl move --to-directoryinstead.
clusterctl restorehas been deprecated. Please use
clusterctl move --from-directoryinstead.
Restore. Please use
Restore. Adds replacements functions
MachinesByCreationTimestamptype has been removed.
ClusterCacheReconciler.Loghas been removed. Use the logger from the context instead.
- A new timeout
nodeVolumeDetachTimeouthas 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-detachhas 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.
Pathfunc in the
sigs.k8s.io/cluster-api/cmd/clusterctl/client/repository.Overriderinterface has been adjusted to also return an error.
- 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-checkannotation. 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
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:
- the default test timeout has been changed to 1h
--junit-reportargument replaces JUnit custom reporter code
- see the “Update tests to Ginkgo v2” PR for a reference example
- 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).
CreateLogFileInputstruct in the E2E test framework for clusterctl has been renamed to
OpenLogFileInputbecause the function will now append to the logfile instead of truncating the content.
Movefunction in E2E test framework for clusterctl has been modified to:
- print the
clusterctl movecommand including the arguments similar to
- log the output to the a
clusterctl-move.logfile at the subdirectory
- print the
- 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:
SkipUpgradecould be set to revert to the old behaviour by making use of the
KUBERNETES_VERSIONvariable and skipping the Kubernetes upgrade.
- cert-manager upgraded from v1.9.1 to v1.10.1.
providerIDis now being strictly checked for equality when compared against Kubernetes node
providerIDdata. 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
IDsubstring part of the full
providerIDstring. Because different providers construct
providerIDstrings differently, the
IDsubstring is not uniformly defined and implemented across providers, and thus the existing
providerIDequality cannot guarantee the correct Machine-Node correlation. It is very unlikely that this new behavior will break existing providers, but FYI: if strict
providerIDequality 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/flagspackage to ensure consistency across CAPI and other providers.