sigs.k8s.io/cluster-api@v1.7.1/docs/book/src/developer/providers/migrations/v1.2-to-v1.3.md (about)

     1  # Cluster API v1.2 compared to v1.3
     2  
     3  This document provides an overview over relevant changes between Cluster API v1.2 and v1.3 for
     4  maintainers of providers and consumers of our Go API.
     5  
     6  ## Minimum Go version
     7  
     8  * The Go version used by Cluster API is Go 1.19.x
     9  
    10  ## Dependencies
    11  
    12  **Note**: Only the most relevant dependencies are listed, `k8s.io/` and `ginkgo`/`gomega` dependencies
    13  in Cluster API are kept in sync with the versions used by `sigs.k8s.io/controller-runtime`.
    14  
    15  - sigs.k8s.io/controller-runtime: v0.12.x => v0.13.x
    16  - sigs.k8s.io/controller-tools: v0.9.x => v0.10.x
    17  - sigs.k8s.io/kind: v0.14.x => v0.18.x
    18  - k8s.io/*: v0.24.x => v0.25.x (derived from controller-runtime)
    19  - github.com/onsi/ginkgo: v1.x => v2.x (derived from controller-runtime)
    20  - k8s.io/kubectl: v0.24.x => 0.25.x
    21  - github.com/joelanford/go-apidiff: 0.4.0 => 0.5.0
    22  
    23  ## Changes by Kind
    24  
    25  ### Deprecation
    26  
    27  - `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.
    28  - `clusterctl init --list-images` has been deprecated and will be removed in a future release. Please use `clusterctl init list-images` instead.
    29  - `clusterctl backup` has been deprecated. Please use `clusterctl move --to-directory` instead.
    30  - `clusterctl restore` has been deprecated. Please use `clusterctl move --from-directory` instead.
    31  - `Client` deprecates `Backup` and `Restore`. Please use `Move`.
    32  - `ObjectMover` deprecates `Backup` and `Restore`. Adds replacements functions `ToDirectory` and `FromDirectory`.
    33  
    34  ### Removals
    35  
    36  - `MachinesByCreationTimestamp` type has been removed.
    37  - `ClusterCacheReconciler.Log` has been removed. Use the logger from the context instead.
    38  
    39  ### API Changes
    40  
    41  - A new timeout `nodeVolumeDetachTimeout` has been introduced that defines how long the controller will spend on waiting for all volumes to be detached.
    42  The default value is 0, meaning that the volume can be detached without any time limitations.
    43  - 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.
    44  - 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](../../architecture/controllers/machine-pool.md#externally-managed-autoscaler).
    45  - The `Path` func in the `sigs.k8s.io/cluster-api/cmd/clusterctl/client/repository.Overrider` interface has been adjusted to also return an error.
    46  
    47  ### Other
    48  
    49  - 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 
    50    core resources via the `clusterctl.cluster.x-k8s.io/skip-crd-name-preflight-check` annotation. The contracts specify:
    51    > The CRD name must have the format produced by sigs.k8s.io/cluster-api/util/contract.CalculateCRDName(Group, Kind)
    52  - The Kubernetes default registry has been changed from `k8s.gcr.io` to `registry.k8s.io`. Kubernetes image promotion currently publishes to both registries. Please
    53    consider publishing manifests which reference the controller images from the new registry (for reference [Cluster API PR](https://github.com/kubernetes-sigs/cluster-api/pull/7478)).
    54  - 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](https://onsi.github.io/ginkgo/MIGRATING_TO_V2), and note:
    55    * the default test timeout has been [changed to 1h](https://onsi.github.io/ginkgo/MIGRATING_TO_V2#timeout-behavior)
    56    * the `--junit-report` argument [replaces JUnit custom reporter](https://onsi.github.io/ginkgo/MIGRATING_TO_V2#improved-reporting-infrastructure) code
    57    * see the ["Update tests to Ginkgo v2" PR](https://github.com/kubernetes-sigs/cluster-api/pull/6906) for a reference example
    58  - Cluster API introduced new [logging guidelines](../../../developer/logging.md). All reconcilers in the core repository were updated
    59    to [log the entire object hierarchy](../../../developer/logging.md#keyvalue-pairs). It would be great if providers would be adjusted
    60    as well to make it possible to cross-reference log entries across providers (please see CAPD for an infra provider reference implementation).
    61  - 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.
    62  - The `Move` function in E2E test framework for clusterctl has been modified to:
    63    * print the `clusterctl move` command including the arguments similar to `Init`.
    64    * log the output to the a `clusterctl-move.log` file at the subdirectory `logs/<namespace>`.
    65  - 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:
    66    * `KUBERNETES_VERSION_UPGRADE_FROM`
    67    * `KUBERNETES_VERSION_UPGRADE_TO`
    68    * `ETCD_VERSION_UPGRADE_TO`
    69    * `COREDNS_VERSION_UPGRADE_TO`
    70    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.
    71  - cert-manager upgraded from v1.9.1 to v1.10.1.
    72  - 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.
    73  - The default minimum TLS version in use by the webhook servers is 1.2.
    74  - 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](https://github.com/kubernetes-sigs/cluster-api/issues/7575). This is not expected to require changes for providers.
    75  
    76  ### Suggested changes for providers
    77  - 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.