diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3b7d1f6ceedf..eb6962d15d07 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -179,14 +179,20 @@ Cluster API maintains the most recent release/releases for all supported API and We are going to remove the apiVersions in upcoming releases: * v1.5: - * Kubernetes API server will stop serving the v1alpha3 apiVersion + * Kubernetes API server stops serving the v1alpha3 apiVersion * v1.6: - * v1alpha3 apiVersion will be removed from the CRDs - * Kubernetes API server will stop serving the v1alpha4 apiVersion + * v1alpha3 apiVersion is removed from the CRDs + * Kubernetes API server stops serving the v1alpha4 apiVersion * v1.7 - * v1alpha4 apiVersion will be removed from the CRDs + * v1alpha4 apiVersion is removed from the CRDs For more details and latest information please see the following issue: [Removing v1alpha3 & v1alpha4 apiVersions](https://github.com/kubernetes-sigs/cluster-api/issues/8038). +Note: Removal of a deprecated APIVersion in Kubernetes [can cause issues with garbage collection by the kube-controller-manager](https://github.com/kubernetes/kubernetes/issues/102641) +This means that some objects which rely on garbage collection for cleanup - e.g. MachineSets and their descendent objects, like Machines and InfrastructureMachines, may not be cleaned up properly if those +objects were created with an APIVersion which is no longer served. +To avoid these issues it's advised to ensure a restart to the kube-controller-manager is done after upgrading to a version of Cluster API which drops support for an APIVersion - e.g. v1.5 and v1.6. +This can be accomplished with any Kubernetes control-plane rollout, including a Kubernetes version upgrade, or by manually stopping and restarting the kube-controller-manager. + ## Contributing a Patch 1. If you haven't already done so, sign a Contributor License Agreement (see details above). diff --git a/REVIEWING.md b/REVIEWING.md index d3248bd439d3..d0897dce90a8 100644 --- a/REVIEWING.md +++ b/REVIEWING.md @@ -106,7 +106,7 @@ By extension, the Cluster API contract includes all the util methods that Cluste making the development of providers simpler and consistent (e.g. everything under `/util` or in `/test/framework`); documentation of the utility is available [here](https://pkg.go.dev/sigs.k8s.io/cluster-api?tab=subdirectories). -The Cluster API contract is linked to the version of the API (e.g. v1alpha3 Contract), and it is expected to +The Cluster API contract is linked to the version of the API (e.g. v1beta1 Contract), and it is expected to provide the same set of guarantees in terms of support window, stability, and upgradability. This makes any change that can impact the Cluster API contract critical and usually: diff --git a/docs/book/src/introduction.md b/docs/book/src/introduction.md index 76bac37a7a23..e45cb45b6b3e 100644 --- a/docs/book/src/introduction.md +++ b/docs/book/src/introduction.md @@ -20,7 +20,7 @@ Also, this [guide](https://github.com/kubernetes/registry.k8s.io/tree/main/docs/