Merge pull request #201 from kubecost/mmd/request-apply-api-docs

1-click request sizing ("apply") feature guide and API reference

api-request-recommendation-apply.md

@@ -0,0 +1,120 @@
+Container Request Recommendation "Apply" APIs
+=============================================
+
+:warning: This feature is in a pre-release (alpha/beta) state. It has limitations. Please read the documentation carefully. :warning:
+
+The "Apply" API for request recommendations takes Kubecost's calculated
+[container request recommendations](https://github.com/kubecost/docs/blob/main/api-request-right-sizing.md) and applies
+them to your cluster. 
+
+This document is an API reference/spec. You can find the feature how-to guide
+[here](https://github.com/kubecost/docs/blob/main/guide-one-click-request-sizing.md).
+
+## Requirements
+
+You must have Kubecost's Cluster Controller [enabled](https://github.com/kubecost/docs/blob/main/controller.md). Cluster
+Controller contains Kubecost's automation features (including the APIs described
+in this document), and thus has write permission to certain resources on your
+cluster. Again, see the [how-to guide for 1-click request
+sizing](https://github.com/kubecost/docs/blob/main/guide-one-click-request-sizing.md) for setup instructions.
+
+## APIs
+
+Apply has dry-run semantics, meaning it is a two step process:
+1. Plan what will happen
+2. Execute the plan
+
+### Plan
+
+The Plan API is available at `http://kubecost.example.com/cluster/requestsizer/plan`. It expects a POST request with a body that is identical to a response from the [request right-sizing recommendation API](https://github.com/kubecost/docs/blob/main/api-request-right-sizing.md).
+
+For example, using `curl`:
+
+```sh
+# Make to `kubectl port-forward -n kubecost service/kubecost-cost-analyzer 9090`
+# or replace 'localhost:9090' with 'kubecost.example.com'
+
+curl -XGET 'http://localhost:9090/model/savings/requestSizing' \
+    -d 'window=2d' \
+    |
+    curl -H "Content-Type: application/json" \
+        -XPOST \
+        --data-binary @- \
+        'http://localhost:9090/cluster/requestsizer/plan'
+```
+
+The API response can be inspected to see what Kubecost will attempt to do before
+running the apply step. The plan may do less than the recommendation, see
+Current Limitations.
+
+```json
+{
+  "cluster-name": {
+    "namespace-name": [
+      {
+        "Name": "controller-name-X",
+        "Kind": "controller-kind-X",
+        "ContainerPlans": {
+          "container-name-X": {
+            "TargetCPURequestMillicores": XX,
+            "TargetRAMRequestBytes": XX,
+          },
+          ...
+        }
+      },
+      ...
+    ],
+    ...
+  },
+  ...
+}
+```
+
+### Apply
+
+The Apply API is available at `http://kubecost.example.com/cluster/requestsizer/plan`. It expects a POST request with a body that is identical to a response from the Plan API.
+
+For example, using `curl`:
+
+```sh
+# Make to `kubectl port-forward -n kubecost service/kubecost-cost-analyzer 9090`
+# or replace 'localhost:9090' with 'kubecost.example.com'
+
+curl -XGET 'http://localhost:9090/model/savings/requestSizing' \
+    -d 'window=2d' \
+    |
+    curl -H "Content-Type: application/json" \
+        -XPOST \
+        --data-binary @- \
+        'http://localhost:9090/cluster/requestsizer/plan' \
+    |
+    curl -H "Content-Type: application/json" \
+        -XPOST \
+        --data-binary @- \
+        'http://localhost:9090/cluster/requestsizer/apply'
+```
+
+The API response includes the original plan, plus some metadata:
+
+```json
+{
+  "TimeInitiated": "",
+  "TimeFinished": "",
+
+  "Errors": ["error message here"],
+  "Warnings": ["non-failure warnings here"],
+  "FromPlan": <the plan passed as argument>
+}
+```
+
+## Current Limitations
+
+- The Apply APIs only "size down," i.e. they will never increase a container requests, only lower them. This is currently done out of an abundance of caution while the APIs are being tested. We don't want to size up requests and cause a cluster that was running fine to run out of capacity, even if setting the requests to a higher level would provide better availability guarantees.
+
+- The Apply APIs only support some controller kinds (Deployments, DaemonSets, StatefulSets, ReplicaSets) at the moment. This is planned to increase soon and is subject to change.
+
+- The Apply APIs do not support sizing Pods without a controller. This is also planned to change.
+
+- The Apply APIs do not support clusters other than the "local" cluster (the cluster that the instance of Kubecost you are interacting with via HTTP is running on). If you are interested in this functionality, please let us know.
+
+<!--- {"article":"","section":"4402829033367","permissiongroup":"1500001277122"} --->

api-request-right-sizing.md

@@ -1,7 +1,7 @@
-Container Request Right-Sizing API
+Container Request Right-Sizing Recommendation API
 ==================================
 
-The container request right-sizing API provides recommendations for
+The container request right-sizing recommendation API provides recommendations for
 [container resource requests](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/)
 based on configurable parameters and estimates the savings from implementing those recommendations
 on a per-container, per-controller level. Of course, if the cluster-level resources stay static then
@@ -83,4 +83,4 @@ curl -G \
 
 Edit this doc on [Github](https://github.com/kubecost/docs/blob/main/api-request-right-sizing.md)
 
-<!--- {"article":"4407595919895","section":"4402829033367","permissiongroup":"1500001277122"} --->
+<!--- {"article":"4407595919895","section":"4402829033367","permissiongroup":"1500001277122"} --->

controller.md

@@ -1,8 +1,15 @@
 Cluster Controller
 ==================
 
-Kubecost cluster controller enables actions like automated cluster scaledown and 1-click cluster resize. 
-This document shows you how to setup and enable this functionality in the Kubecost product. 
+Kubecost's cluster controller contains contains Kubecost's automation features,
+and thus has write permission to certain resources on your cluster.
+
+Cluster controller enables actions like:
+- automated cluster scaledown
+- 1-click cluster right-sizing
+- [1-click request right-sizing](./guide-one-click-request-sizing.md)
+
+This document shows you how to setup and enable this functionality in the Kubecost product.
 
 Note: Cluster controller supports GKE and EKS clusters and is currently in **ALPHA**.
 
@@ -58,4 +65,4 @@ You may also enable via `--set` when running helm install:
 
 Edit this doc on [Github](https://github.com/kubecost/docs/blob/main/controller.md)
 
-<!--- {"article":"4407595938327","section":"4402815636375","permissiongroup":"1500001277122"} --->
+<!--- {"article":"4407595938327","section":"4402815636375","permissiongroup":"1500001277122"} --->

guide-one-click-request-sizing.md

@@ -0,0 +1,64 @@
+Guide: 1-click request sizing
+=============================
+
+:warning: This feature is in a pre-release (alpha/beta) state. It has limitations. Please read the documentation carefully. :warning:
+
+1-click request sizing is a feature that will instantly update [container
+resource
+requests](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits)
+in your cluster based on Kubecost's sizing
+[recommendations](https://github.com/kubecost/docs/blob/main/api-request-right-sizing.md). This allows you to instantly
+optimize resource allocation across your entire cluster, without fiddling with
+excessive YAML or arcane `kubectl` commands. You can easily eliminate resource
+over-allocation in your cluster, which paves the way for vast savings via
+cluster right-sizing and other optimizations.
+
+## Setup
+
+Install Kubecost with cluster controller enabled, which is the only Kubecost
+component with write permission to your cluster.
+
+```bash
+# Make sure the Kubecost helm repo is set up! See kubecost.com/install
+
+# This command will install Kubecost if you haven't already. You can use
+# "--set clusterController.enabled=true" to get cluster controller running if 
+# you already have Kubecost installed.
+helm upgrade \
+    -i \
+    --create-namespace kubecost \
+    kubecost/cost-analyzer \
+    --set kubecostToken="aWljaGFlbEBrdQQY29zdljb203yadf98" \
+    --set clusterController.enabled=true
+```
+
+## Using 1-click request sizing
+
+1. Visit the request sizing page of your Kubecost installation
+   ```bash
+   kubectl port-forward \
+       -n kubecost \
+       service/kubecost-cost-analyzer \
+       9090
+   ```
+
+   Then visit [http://localhost:9090/request-sizing.html](http://localhost:9090/request-sizing.html)
+
+2. Modify the request sizing settings, like profile, window, and filters, until
+   you have a set of recommendations you are ready to apply to your cluster.
+
+3. Click the "Automatically implement recommendations" button.
+
+   ![](https://raw.githubusercontent.com/kubecost/docs/main/images/one-click-request-sizing/configured-with-button.png)
+
+4. Confirm!
+
+   ![](https://raw.githubusercontent.com/kubecost/docs/main/images/one-click-request-sizing/confirm-dialog.png)
+
+## Technical details
+
+If you want to learn more about the APIs that power 1-click request sizing,
+including their limitations, see [the API
+documentation](https://github.com/kubecost/docs/blob/main/api-request-recommendation-apply.md).
+
+<!--- {"article":"","section":"4402815656599","permissiongroup":"1500001277122"} --->