Merge pull request #246 from kubecost/mmd/update-cluster-controller-s…

…caledown

Update cluster controller docs with more detail about turndown and breaking changes

controller.md

@@ -1,11 +1,11 @@
 Cluster Controller
 ==================
 
-Kubecost's cluster controller contains Kubecost's automation features,
+Kubecost's Cluster Controller contains Kubecost's automation features,
 and thus has write permission to certain resources on your cluster.
 
 Cluster controller enables actions like:
-- automated cluster scaledown
+- Automated cluster scaledown
 - 1-click cluster right-sizing
 - [1-click request right-sizing](./guide-one-click-request-sizing.md)
 
@@ -63,6 +63,12 @@ You may also enable via `--set` when running helm install:
 --set clusterController.enabled=true
 ```
 
+## Using automated cluster scaledown
+
+Cluster Controller wraps all functionality in and provides the same interface/CRDs as https://github.com/kubecost/cluster-turndown. Follow that documentation for usage instructions. You can safely ignore the deployment instructions in that README because you have already deployed Cluster Controller.
+
+> :warning: The v1 -> v2 breaking change mentioned in the cluster-turndown README also applies to Cluster Controller, but for v0.0.6 -> v0.1.0. Cluster Controller was upgraded to v0.1.0 in v1.94 of Kubecost. Follow the [migration guide](https://github.com/kubecost/docs/blob/main/v1-94-turndown-schedule-migration-guide.md) if you use turndown in a version of Kubecost < v1.94 and are upgrading to v1.94+ of Kubecost.
+
 Edit this doc on [GitHub](https://github.com/kubecost/docs/blob/main/controller.md)
 
 <!--- {"article":"4407595938327","section":"4402815636375","permissiongroup":"1500001277122"} --->

v1-94-turndown-schedule-migration-guide.md

@@ -0,0 +1,67 @@
+v1.94+ TurndownSchedule migration guide
+=======================================
+
+In v1.94 of Kubecost, the `turndownschedules.kubecost.k8s.io/v1alpha1` Custom Resource Definition (CRD) was [moved](https://github.com/kubecost/cost-analyzer-helm-chart/pull/1444) to `turndownschedules.kubecost.com/v1alpha1` to adhere to [Kubernetes policy for CRD domain namespacing](https://github.com/kubernetes/enhancements/pull/1111). This is a breaking change for users of Cluster Controller's turndown functionality. Please follow this guide for a successful migration of your turndown schedule resources.
+
+> As part of this change, the CRD was updated to use `apiextensions.k8s.io/v1` because `v1beta1` was removed in K8s v1.22. If using Kubecost v1.94+, Cluster Controller's turndown functionality will not work on K8s versions before the introduction of `apiextensions.k8s.io/v1`.
+
+# Situation 1: You have deployed cluster controller but don't use turndown
+
+In this situation, you've deployed Kubecost's Cluster Controller at some point
+using `--set clusterController.enabled=true`, but you don't use the turndown functionality.
+
+That means that this command should return one line:
+
+    kubectl get crd turndownschedules.kubecost.k8s.io
+
+And this command should return no resources:
+
+    kubectl get turndownschedules.kubecost.k8s.io
+
+This situation is easy! You can do nothing, and turndown should continue to behave correctly because `kubectl get turndownschedule` and related commands will correctly default to the new `turndownschedules.kubecost.com/v1alpha1` CRD after you upgrade to Kubecost v1.94 or higher.
+
+If you would like to be fastidious and clean up the old CRD, simply run `kubectl delete crd turndownschedules.kubecost.k8s.io` after upgrading Kubecost to v1.94 or higher.
+
+
+# Situation 2: You currently use turndown
+
+In this situation, you've deployed Kubecost's Cluster Controller at some point using `--set clusterController.enabled=true` and you have at least one `turndownschedule.kubecost.k8s.io` resource currently present in your cluster.
+
+That means that this command should return one line:
+
+    kubectl get crd turndownschedules.kubecost.k8s.io
+
+And this command should return at least one resource:
+
+    kubectl get turndownschedules.kubecost.k8s.io
+
+We have a few steps to perform if you want Cluster Controller's turndown functionality to continue to behave according to your already-defined turndown schedules.
+
+1.  Upgrade Kubecost to v1.94 or higher with `--set clusterController.enabled=true`
+2.  Make sure the new CRD has been defined after your Kubecost upgrade.
+
+    This command should return a line:
+
+        kubectl get crd turndownschedules.kubecost.com
+
+3.  Copy your existing `turndownschedules.kubecost.k8s.io` resources into the new CRD.
+
+        kubectl get turndownschedules.kubecost.k8s.io -o yaml \
+            | sed 's|kubecost.k8s.io|kubecost.com|' \
+            | kubectl apply -f -
+
+4.  (optional) Delete the old `turndownschedules.kubecost.k8s.io` CRD
+
+    Because the CRDs have a finalizer on them, we have to follow [this workaround](https://github.com/kubernetes/kubernetes/issues/60538#issuecomment-369099998) to remove the finalizer from our old resources. This lets us clean up without locking up.
+
+        kubectl patch \
+            crd/turndownschedules.kubecost.k8s.io \
+            -p '{"metadata":{"finalizers":[]}}' \
+            --type=merge
+
+    > The following command may be unnecessary because Helm should automatically remove the `turndownschedules.kubecost.k8s.io` resource during the upgrade. The removal will remain in a pending state until the finalizer patch above is implemented.
+
+        kubectl delete crd turndownschedules.kubecost.k8s.io
+
+
+<!--- {"article":"","section":"4402815636375","permissiongroup":"1500001277122"} --->