Merge pull request kubernetes-sigs#8740 from killianmuldoon/pr-add-removal-remediation-note

📖 Add note about v1alpha3 removal to book

Author: k8s-ci-robot

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).

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:

docs/book/src/introduction.md

@@ -20,7 +20,7 @@ Also, this [guide](https://github.com/kubernetes/registry.k8s.io/tree/main/docs/
 <aside class="note">
 <h1>Deprecated API removal</h1>
 
-- API version v1alpha3 support will be removed in the upcoming release of v1.5
+- API version v1alpha3 support is no longer served in release v1.5
 - API version v1alpha4 support will be removed in the upcoming release of v1.6
 
 Review the [support-and-guarantees](./CONTRIBUTING.md#support-and-guarantees) section of the

docs/proposals/20210210-insulate-users-from-kubeadm-API-changes.md

@@ -77,7 +77,7 @@ because types are already different (see background info in the implementation d
   specs for v1alpha4.
 - Define how to use the right version of the kubeadm types generating our kubeadm yaml
   file and when interacting with the kubeadm-config ConfigMap.
-- Ensure a clean and smooth v1alpha3 to v1aplha4 upgrade experience.
+- Ensure a clean and smooth v1alpha3 to v1alpha4 upgrade experience.
 
 ### Non-Goals