Welcome to the Kubecost API library! This directory will show you how Kubecost APIs can assist in monitoring, maintaining, and optimizing your cloud spend. Learn also how Kubecost APIs power different features of the UI below.
The Allocation API retrieves cost allocation information for any Kubernetes concept, e.g. cost by namespace, label, deployment, service, and more. This API is directly integrated with the Kubecost ETL caching layer and CSV pipeline so it can scale for large clusters.
The Allocation Trends API compares cost usage between two windows of the same duration and presents a percentage value showing the change in cost.
The Assets API retrieves the backing cost data broken down by individual Kubernetes assets (e.g. node, disk, etc.), and provides various aggregations of this data. Optionally provides the ability to integrate with external cloud assets.
The Asset Diff API compares two asset sets between two windows of the same duration and accumulates the results.
The Cloud Costs API retrieves cloud cost data from cloud providers by reading cost and usage reports.
The Cloud Cost Trends API compares cost usage between two windows of the same duration and presents a percentage value showing the change in cloud costs.
The External Costs API displays costs related to third party services, currently limited to Datadog.
The Budget API allows you to establish spending budget rules for your workloads to ensure you don't go over your allotted budget.
The Forecast API uses a predictive learning model to approximate future spend of Allocation, Assets, or Cloud Cost data.
The Cost Events Audit API presents recent changes at the cluster level.
The Prediction API takes Kubernetes objects as input and produces an estimation of the cost impact when making changes to your workload.
The Events API provides a log of different occurrences in your workload in order to help with troubleshooting. Logs generated with this API are helpful for submitting bug reports.
These diagnostic APIs for Aggregator are designed to assist in troubleshooting without inspecting the PV directly.
Savings endpoints provide cost optimization insights. The following savings endpoints are available at http://<kubecost-address>/model/ENDPOINT:
| Endpoint | Description |
|---|---|
/savings | Provides cluster-level potential savings estimates based on specific savings opportunities available in other endpoints. |
/savings/clusterSizingETL | Provides recommendations for sizing clusters (node types and quantities). |
/savings/requestSizingV2 | Provides recommendations for setting container resource requests. |
/savings/abandonedWorkloads | List abandoned workloads based on network traffic. |
/cluster/requestsizer/planV2 | Applies Kubecost's container request recommendations to your cluster. |
/projectDisks | List orphaned disks. |
/projectAddresses | List orphaned IP addresses. |
Many, but not all, Kubecost APIs power different features in the Kubecost UI. The UI counterpart may not fully reflect all functionality of the corresponding API. Please consult the original API docs for complete details.
| API Name | UI Equivalent |
|---|---|
| Allocation API | Allocations dashboard |
| Allocation/Cloud Cost Explorer Trends API | Allocations/Cloud Cost Explorer dashboards, Total cost column percentage |
| Assets API | Assets dashboard |
| Cloud Cost API | Cloud Costs Explorer dashboard |
| External Costs API | External Costs dashboard |
| Budget API | Budgets dashboard |
| Cost Events Audit API | Audits dashboard |
| Predict API | Audits dashboard, Estimated monthly cost impact |
| Savings API | Savings dashboard |
| Cluster Right Sizing Recommendation API | Cluster Sizing Recommendations page |
| Container Request Right Sizing Recommendation API | Request right sizing recommendations page |
| Abandoned Workloads API | Abandoned Workloads page |
Several Kubecost APIs use the window parameter to establish the duration of time Kubecost should sample to provide cost metrics, right-sizing recommendations, or other savings information. The following APIs accept window as parameter:
- Allocation API
- Allocation Trends API
- Assets API
- Cloud Cost API
- Cloud Cost Trends API
- Spec Cost Prediction API
- Events API
- Aggregator Diagnostic APIs
- Cluster Right-Sizing Recommendation API
- Container Request Right-Sizing Recommendation API
Acceptable formats for using window parameter include:
- Common units of time: "15m", "24h", "7d", "48h", etc.
- Relative units of time: "today", "yesterday", "week", "month", "lastweek", "lastmonth"
- Start and end unix timestamps: "1586822400,1586908800"
- Start and end UTC RFC3339 pairs: "2020-04-01T00:00:00Z,2020-04-03T00:00:00Z"
Several Kubecost APIs have an additional /topline endpoint which will accept all parameters for corresponding APIs, but will total all costs by category. These categories should mirror cost metric column totals found across various Kubecost UI dashboards. The following APIs accept /topline as an endpoint:
- Allocation API
- Assets API
- Request Right-Sizing Recommendation API
- Abandoned Workloads API
You must still provide a value for window when querying a /topline endpoint.
An example of using /topline to view total costs for Assets data would look like:
GET http://<your-kubecost-address>/model/assets/topline?window=...
When querying for Allocation data, you must add a /summary before topline, and the query for that will look like:
GET http://<your-kubecost-address>/model/allocation/summary/topline?window=...
The offset and limit parameters apply to multiple querying APIs to introduce pagination to your results in order to avoid lengthy payloads. Similar to how Kubecost's UI pages display your queried items in limited amounts per page across multiple pages, these two parameters allow your to filter your displayed results. These following APIs accept offset and limit as parameters:
- Allocation API
- Assets API
- Cloud Cost API
Both parameters must be formatted as integers. offset refers to how many line items you'd like to offset. limit controls how many results per page you would like to see. This means when offset is equal to limit, you will be offsetting an entire page of line items. You can multiply your limit value by the number of pages you'd like to offset to obtain an offset value. When using limit, you must also set the parameter accumulate to true when possible in order to receive a single list of line items. The order of items across all pages is determined by total cost, where the largest costs are presented first.
An example of using these parameters in an Allocation query to see results starting from the third page of line items:
GET http://<your-kubecost-address>/model/allocation?window=3d&offset=20&limit=10&accumulate=true