Container Request Recommendation Apply/Plan APIs

This feature is in beta. Please read the documentation carefully.

The Apply/Plan APIs for request recommendations takes Kubecost's calculated container request recommendations and applies them to your cluster.

Prerequisites

To use the Plan/Apply APIs, you must first enable Kubecost's Cluster Controller. The 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.

APIs

Apply has dry-run semantics, meaning it is a two-step process:

1. Plan what will happen (Plan API)

2. Execute the plan (Apply API)

Plan API

Plan API

POST http://<your-kubecost-address>/cluster/requestsizer/planV2

It expects a request with a body that is identical to a response from the request right-sizing recommendation API.

The versions of the Request Right Sizing Recommendation API and the Plan API need to match to produce a successful right sizing plan. For example, if you choose to use the deprecated Request Right Sizing Recommendation API V1 (which is not officially supported), you must use /plan, not /planV2. The outputs generated by /plan and /planV2 should be identical.

Examine the cURL example below. 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.

Request

# Make to `kubectl port-forward -n kubecost service/kubecost-cost-analyzer 9090` or replace 'localhost:9090' with your Kubecost address

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'

Response

{
  "cluster-name": {
    "namespace-name": [
      {
        "Name": "controller-name-X",
        "Kind": "controller-kind-X",
        "ContainerPlans": {
          "container-name-X": {
            "TargetCPURequestMillicores": 0.00,
            "TargetRAMRequestBytes": 0.00,
          },
          ...
        }
      },
      ...
    ],
    ...
  },
  ...
}

Apply API

Apply API

GET http://kubecost.example.com/cluster/requestsizer/apply

It expects a request with a body that is identical to a response from the Plan API.

The Apply API accepts outputs from both /plan and /planV2 endpoints. There is no need to specify the version in your endpoint.

In the cURL example below, the API response includes the original plan, plus some metadata:

Request

# 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'

Response

{
  "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. This is to prevent a well-running cluster to scale up and 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).