Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
GET http://<your-kubecost-address>/model/assets
The Assets API retrieves backing cost data broken down by individual assets in your cluster but also provides various aggregations of this data.
| Name | Type | Description |
|---|---|---|
GET http://<your-kubecost-address>/model/assets
The Assets API retrieves backing cost data broken down by individual assets in your cluster but also provides various aggregations of this data. This version of the Assets API should only be consulted for users who have configured Kubecost Aggregator
window parameter:Acceptable formats for using window parameter include:
"15m", "24h", "7d", "48h", etc.
"today", "yesterday", "week", "month", "lastweek", "lastmonth"
"1586822400,1586908800", etc. (start and end unix timestamps)
"2020-04-01T00:00:00Z,2020-04-03T00:00:00Z", etc. (start and end UTC RFC3339 pairs)
Retrieve assets cost data for the past week, aggregated by type, and as cumulative object data:
http://localhost:9090/model/assets?window=1w&aggregate=type&accumulate=true
Retrieve all GCP costs, aggregated by asset type, in the past five days:
http://localhost:9090/model/assets?window=5d&aggregate=type&filterProviders=GCP
/topline endpoint to view cost totals across query (Aggregator only)/topline is an optional API endpoint which can be added to your Assets query via .../model/assets/topline?window=... to provide a condensed overview of your total cost metrics including all line items sampled. You will receive a single list which sums the values per all items queried (totalCost), where numResults displays the total number of items sampled.
As of v1.106, Prometheus queries for CPU and RAM mode breakdown are disabled by default. To receive these metrics, you must manually enable them by setting the Helm flag:
This will enable fields ramBreakdown, cpuBreakdown, and breakdown in the output of all future Assets queries.
| Name | Type | Description |
|---|---|---|
window*
string
Dictates the applicable window for measuring historical asset cost.
aggregate
string
Used to consolidate cost model data. Supported values are account, cluster, project, providerid, provider, and type. Passing an empty value for this parameter or none at all returns data by an individual asset. Supports multi-aggregation (aggregation of multiple categories) in a comma separated list, such as aggregate=account,project.
accumulate
boolean
When set to false, this endpoint returns daily time series data vs cumulative data. Default value is false.
disableAdjustments
boolean
When set to true, zeros out all adjustments from cloud provider reconciliation, which would otherwise change the totalCost. Default value is false.
format
string
When set to csv, will download an accumulated version of the asset results in CSV format. By default, results will be in JSON format.
filter
string
Filter your results by any category which you can aggregate by, can support multiple filterable items in the same category in a comma-separated list. For example, to filter results by clusters A and B, use filter=cluster:clusterA,clusterB See our Filter Parameters doc for a complete explanation of how to use filters and what categories are supported.
step
string
Duration of each individual data metric across the window. Accepts 1h, 1d, or 1w. If left blank, defaults to longest step duration available based on level of granularity of data represented by window.
window*
string
Dictates the applicable window for measuring historical asset cost.
aggregate
string
Used to consolidate cost model data. Supported values are account, cluster, project, providerid, provider, and type. Passing an empty value for this parameter or none at all returns data by an individual asset. Supports multi-aggregation (aggregation of multiple categories) in a comma separated list, such as aggregate=account,project.
accumulate
boolean
When set to false, this endpoint returns daily time series data vs cumulative data. Default value is false.
disableAdjustments
boolean
When set to true, zeros out all adjustments from cloud provider reconciliation, which would otherwise change the totalCost. Default value is false.
format
string
When set to csv, will download an accumulated version of the asset results in CSV format. By default, results will be in JSON format.
offset
int
Refers to the number of pages you are searching through which will increase by integers for the amount of pages you want to skip. Starting value is 0, representing the first page of results.
limit
int
Refers to the number of line items per page. Pair with the offset parameter to filter your payload to specific sections of line items. You should also set accumulate=true to obtain a single list of line items, otherwise you will receive a group of line items per interval of time being sampled. Paginates by all five item types, and will provide lists for all five types.
filter
string
Filter your results by any category which you can aggregate by, can support multiple filterable items in the same category in a comma-separated list. For example, to filter results by clusters A and B, use filter=cluster:clusterA,clusterB See our Filter Parameters doc for a complete explanation of how to use filters and what categories are supported.
When ingesting billing data from cloud service providers (CSP), Kubecost records multiple cost metrics for each item. These cost metrics represent different pricing models which may be useful depending on what needs to be accomplished. The cost metrics currently supported by Cloud Cost are:
ListCost
NetCost
AmortizedNetCost
InvoicedCost
AmortizedCost
Each cost metric includes a Cost and a KubernetesPercent field. An unaggregated CloudCost query should have a 1 or a 0 in the KubernetesPercent field of all of its cost metrics. When it becomes aggregated, this value can become a percentage. It is necessary to keep track of these separately because differences in cost metrics will cause this value to diverge. For example, aggregating a Cloud Cost representing a Kubernetes node that has a reserved instance applied to it, and a non-Kubernetes node of the same type but with no reserved instance discount. See below:
The KubernetesPercent on the AmortizedNetCost is calculated at 33% from $1 which was 100% Kubernetes spend and $2 that were 0% Kubernetes spend in that dimension.
The current Cloud Cost schema is optimistic in that it provides space for cost metrics that may not yet be available from some providers. As the FOCUS Spec gains more adoption among CSPs, all fields will be populated with values that match the definitions. For now, some values on certain providers are being populated with their nearest approximate. This section outlines how each value is populated on each CSP.
To calculate the 'K8s Utilization', Kubecost must first determine if a resources is part of a Kubernetes cluster or not.
If a tag or label in the list below is present on the billing export, Kubecost will consider those costs part of the 'K8s Utilization' calculation. This will not always be 100% accurate in all situations.
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.
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.
Apply has dry-run semantics, meaning it is a two-step process:
Plan what will happen (Plan API)
Execute the plan (Apply 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.
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:
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).
This document outlines the filtering language added to the Allocation API in v1.96 of Kubecost, superseding Kubecost's original filtering parameters (e.g. filterNamespaces=), now referred to as v1 filters. v2 filters introduce support for "not equals" (e.g. namespace != kubecost) queries while maintaining extensibility.
v1 filters will continue to be supported in all relevant APIs. APIs will first check for the filter= parameter. If it is present, v2 filters will be used. If it is not present, APIs will attempt to use v1 filters.
v2 filters can be used via the filter= parameter in supported APIs. Supported APIs are currently:
Allocation/Cloud Cost Trends API (Kubecost Aggregator only)
The available fields for filtering depend on the API being queried.
The supported filter fields as of v1.96 are:
cluster
node
namespace
controllerName
controllerKind (e.g. deployment, daemonset)
container
pod
services
label
annotation (same syntax as label, see examples)
Added in v1.105 of Kubecost:
department
environment
owner
product
team
V2 filter support was added to the /model/assets API in v1.105 of Kubecost.
In v1.105 of Kubecost:
name
assetType (e.g. node, disk, network, etc.)
category (e.g. Compute, Management)
cluster
project
provider
providerID
account
service
label
The supported filter operators in v1.96 of Kubecost are:
: Equality
For string fields (e.g. namespace): equality
For slice/array fields (e.g. services): slice contains at least one value equal (equivalent to ~:)
For map fields (e.g. labels): map contains key (equivalent to ~:)
!: Inequality, or "not contains" if an array type
Added in v1.105 of Kubecost:
~: Contains
For string fields: contains
For slice fields: slice contains at least one value equal (equivalent to :)
For map fields: map contains key (equivalent to :)
!~: NotContains, inverse of ~:
<~: ContainsPrefix
For string fields: string starts with
For slice fields: slice contains at least one value that starts with
For map fields: map contains at least one key that starts with
!<~: NotContainsPrefix, inverse of <~:
~>: ContainsSuffix
For string fields: strings ends with
For slice fields: slice contains at least one value that ends with
For map fields: map contains at least one key that ends with
!~>: NotContainsSuffix, inverse of ~>:
Filter values are strings surrounded by ". Multiple values can be separated by commas ,.
Individual filters can be joined by + (representing logical AND) or | (representing logical OR). To use + and | in the same filter expression, scope must be denoted via ( and ). See examples.
Here are some example filters to see how the filtering language works:
namespace:"kubecost"+container:"cost-model" Return only results that are in the kubecost namespace and are for the cost-model container.
cluster:"cluster-one"+label[app]:"cost-analyzer" Return only results in cluster cluster-one that are labeled with app=cost-analyzer.
cluster!:"cluster-one" Ignore results from cluster cluster-one
namespace:"kubecost","kube-system" Return only results from namespaces kubecost and kube-system.
namespace!:"kubecost","kube-system" Return results for all namespaces except kubecost and kube-system.
For example, in an Allocation query:
The format is essentially: <filter field> <filter op> <filter value>
To see the filter language's formal grammar and lexer/parser implementation, check out OpenCost's pkg/filter21/ast.
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.
Throughout our API documentation, you may see two separate endpoints for the same API, with one labeled 'Aggrgegator-only', or a subsection in an article for Aggregator-only parameters. Those endpoints or parameters are only for users who have configured Kubecost Aggregator. If you do not have Aggregator configured in your environment, do not use those Aggregator endpoints or parameters.
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 Budget API allows you to establish spending budget rules for your workload across clusters and namespaces to ensure you don't go over your allotted budget.
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.
Savings endpoints provide cost optimization insights. The following savings endpoints are available at http://<kubecost-address>/model/ENDPOINT:
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.
GET http://<your-kubecost-address>/model/allocation/trends
Analyzes change in total cost of allocations relative to a previous window of the same size
| Name | Type | Description |
|---|---|---|
GET http://<your-kubecost-address>/model/allocation/trends
Analyzes change in allocated costs relative to a previous window of the same size. This Allocation Trends API should only be consulted for users who have configured [Kubecost Aggregator](/install-and-configure/install/multi-cluster/federated-etl/aggregator.md).
The Allocation Trends API determines changes in resource cost usage over time based on the interval set window parameter and provides that information via the schema field value. Cost usage for the current window sampled will be compared with the previous window, the window directly before the current window of the same size interval. For example, for window=3d, Kubecost will output cost usage for the past three days compared to cost usage of the three days before the start of the window. This means a total of six days of allocation data must be available and sampled in order to provide an accurate value.
The equation for calculating value is: value=current/previous - 1
Receiving a positive value means your more recent totalCost has increased compared to the previous window. A negative value means spending has decreased.
It's important to recognize when a resource is not detected to exist in the previous window. This is designated by the field IsInfinite=true, which means the allocation could not be determined to exist. Otherwise, the cause of an unexpected or major trend change could be misattributed. The field isNaN, meaning not a number, refers to if the value is unreal. If so, isNan should return true, which means there was an error during calculation. Both fields should return false during a successful query.
In the example output below, value is expressed as -0.27..., meaning spending has decreased in the current window by roughly 27% from the previous window.
names parameternames is a mandatory parameter which determines the sequence of items returned, based on whatever the query is aggregating by. For example, when using aggregate=namespace, the user should provide a comma-separated list of all namespaces they wish to see trend values for in this category. In this case, they should provide names=kubecost,aggregator,kube-system... to receive a list of trend values for all provided namespaces as ordered. If the user does not provide a value for aggregate, they must still use the names parameter to list all line items requested.
Trend values are converted into percentages in the Kubecost Allocations page, calculated based on your current query. Trends will be presented in the rightmost column, next to your Total cost. The window parameter is determined by your selected date range in the top right of the page. The default is Last 7 days (window=7d). The equation value*100 is used to provide percentages.
Requests with large time intervals for window can result in an error. The recommended maximum interval for window is 7 days. A failed response will show a N/A inside a gray bubble in the UI with no percentage returned.
The Trends API does not currently support cost comparisons besides totalCost.
GET http://{kubecost-addresss}/model/assets/diff
The Asset Diff API provides a diff of two windows that returns all the added, removed, or cost changed assets from the later window (before parameter) to the earlier window (after parameter). This endpoint does a comparison of two asset sets in the given windows and accumulates the results.
| Name | Type | Description |
|---|---|---|
Compare yesterday's assets to today's assets:
http://localhost:9090/model/assets/diff?before=yesterday&after=today
Compare assets from 5 days ago to assets from the last day:
http://localhost:9090/model/assets/diff?before=1d offset 5d&after=1d
Compare assets from last month to assets from this month:
http://localhost:9090/model/assets/diff?before=lastmonth&after=month
Compare assets on 07/01/2022 to assets on 07/06/2022:
http://localhost:9090/model/assets/diff?before=2022-07-01T00:00:00Z,2022-07-02T00:00:00Z&after=2022-07-06T00:00:00Z,2022-07-07T00:00:00Z
Compare yesterday's assets to today's assets, displaying all assets that have a total cost change of 10% or more:
http://localhost:9090/model/assets/diff?before=yesterday&after=today&costChangeRatio=0.1
The Cloud Cost API cannot be used until you have enabled Cloud Cost via Helm. See Kubecost's Cloud Cost Explorer doc for instructions.
The Cloud Cost API provides multiple endpoints to obtain accurate cost information from your cloud service providers (CSPs), including data available from cloud billing reports (such as AWS' Cost and Usage Report (CUR)).
There are three distinct endpoints for using the Cloud Cost API. The default endpoint for querying Cloud Costs should be /model/cloudCost/view.
GET http://<your-kubecost-address>/model/cloudCost/view
Samples full granularity of cloud costs from cloud billing report (ex. AWS' Cost and Usage Report)
| Name | Type | Description |
|---|---|---|
The endpoint /model/cloudCost/top will use all parameters of /model/cloudCost/view listed above, except for CostMetric. This is because /top samples full granularity from your cloud billing reports and will return information for all four accepted metric types (see below for more information on these types).
The endpoint /view contains all parameters for /model/CloudCost/aggregate, and if your /view query parameters are in a subset of /aggregate, your payload will be pulled from /aggregate instead (this payload will return a larger amount of information than /view). Otherwise, your /view query will pull from /top.
GET http://<your-kubecost-address>/model/cloudCost/aggregate
Query cloud cost aggregate data
CostMetric parameterUsing the endpoint /model/cloudCost/top will accept all parameters of model/cloudCost/view except for MetricCost.
CostMetric values are based on and calculated following standard FinOps dimensions and metrics. The four available metrics supported by the Cloud Cost API are:
Providing a value for CostMetric is optional, but it will default to AmortizedNetCost if not otherwise provided.
kubernetesPercentEach CostMetric also has a kubernetesPercent value. Unaggregated, this value will be 0 or 1. When you aggregate, kubernetesPercent is determined by multiplying the costMetric cost by its kubernetesPercent and aggregating that value as kubernetesCost for that costMetric. That kubernetesCost is then divided by the aggregated total costs to determine the new kubernetesPercent. Since this process results in unique values for each costMetric, this value is included as part of the cost metric.
These APIs are designed to help troubleshoot and provide diagnostics for Kubecost's cloud integration features like Cloud Usage and reconciliation. For an explanation of these integration features, review Kubecost's cloud processes.
To review the provider parameter for rebuild/run APIs, see Cloud Stores.
GET http://<kubecost-address>/model/etl/cloudUsage/rebuild
Restarts Cloud Usage pipeline. This operation ends the currently running Cloud Usage pipeline and rebuilds historic CloudUsages in the Daily CloudUsage Store.
| Name | Type | Description |
|---|---|---|
GET http://<kubecost-address>/model/etl/cloudUsage/repair
Reruns queries for Cloud Usages in the given window for the given Cloud Store or all Cloud Stores if no provider is set.
GET http://<kubecost-address>/model/etl/asset/reconciliation/run
Completely restart reconciliation pipeline. This operation ends the currently running reconciliation pipeline and reconciles historic Assets in the Daily Asset Store.
GET http://<kubecost-address>/model/etl/asset/reconciliation/repair
Reruns queries for reconciliation in the given window for the given Cloud Store or all Cloud Stores if no provider is set.
GET http://<kubecost-address>/model/etl/status
Returns a status object for the ETL. This includes sections for allocation, assets, and cloud.
This feature is only available in Kubecost Aggregator.
GET http://<your-kubecost-address>/model/cloudCost/view/trends
Analyzes change in cloud costs relative to a previous window of the same size
| Name | Type | Description |
|---|---|---|
The Trends API determines changes in resource cost usage over time based on the interval set window parameter and provides that information via the schema field value. Cost usage for the current window sampled will be compared with comparisonWindow, the window directly before the current window of the same size interval. For example, for window=3d, Kubecost will output cost usage for the past three days compared to cost usage of the three days before the start of the window. This means a total of six days of cloud cost data are sampled in order to provide an accurate value.
The equation for calculating value is: value=window/comparisonWindow - 1
Receiving a positive value means spending has increased in the current window when compared to comparisonWindow. A negative value means spending has decreased.
It's important to recognize when a resource is not detected to exist in the previous window. This is designated by the field IsInfinite=true, which means the allocation could not be determined to exist. Otherwise, the cause of an unexpected or major trend change could be misattributed. The field isNaN, meaning not a number, refers to if the value is unreal. If so, isNan should return true, which means there was an error during calculation. Both fields should return false during a successful query.
In the example output below, value is expressed as -0.147, meaning spending has decreased for project-123 by roughly 14.7%.
Trend values are converted into percentages in the Kubecost Cloud Costs Explorer page, calculated based on your current query. Trends will be presented in the rightmost column, next to your Total cost. The window parameter is determined by your selected date range in the top right of the page. The default is Last 7 days (window=7d). The equation value*100 is used to provide percentages.
names parameternames is a mandatory parameter which determines the sequence of items returned, based on whatever the query is aggregating by. For example, when using aggregate=provider, the user should provide a comma-separated list of all providers they wish to see trend values for in this category. In this case, they should provide names=AWS,GCP,Azure to receive a list of trend values for all three providers. If the user does not provide a value for aggregate, they must still use the names parameter to list all line items requested.
Throughout our API documentation, we use localhost:9090 as the default Kubecost URL, but your Kubecost instance may be exposed by a service or ingress. To reach Kubecost at port 9090, run: kubectl port-forward deployment/kubecost-cost-analyzer -n kubecost 9090. When querying the cost-model container directly (ex. localhost:9003), the /model part of the URI should be removed.
GET http://<your-kubecost-address>/model/allocation
The Allocation API is the preferred way to query for costs and resources allocated to Kubernetes workloads and optionally aggregated by Kubernetes concepts like namespace, controller, and label. Data is served from one of Kubecost's ETL pipelines.
| Name | Type | Description |
|---|---|---|
GET http://<your-kubecost-address>/model/allocation
The Allocation API is the preferred way to query for costs and resources allocated to Kubernetes workloads and optionally aggregated by Kubernetes concepts like namespace, controller, and label. This Allocation API should only be consulted for users who have configured Kubecost Aggregator.
Request allocation data for each 24-hour period in the last three days, aggregated by namespace:
Querying for window=3d should return a range of four sets because the queried range will overlap with four precomputed 24-hour sets, each aligned to the configured time zone. For example, querying window=3d on 2021/01/04T12:00:00 will return:
2021/01/04 00:00:00 until 2021/01/04T12:00:00 (now)
2021/01/03 00:00:00 until 2021/01/04 00:00:00
2021/01/02 00:00:00 until 2021/01/03 00:00:00
2021/01/01 00:00:00 until 2021/01/02 00:00:00
See Querying for the full list of arguments and Examples for more example queries.
__idle__ refers to resources on a cluster that were not dedicated to a Kubernetes object (e.g. unused CPU core-hours on a node). An idle resource can be shared (proportionally or evenly) with the other allocations from the same cluster. (See the argument shareIdle.)
__unallocated__ refers to aggregated allocations without the selected aggregate field; e.g. aggregating by label:app might produce an __unallocated__ allocation composed of allocations without the app label.
__unmounted__ (or "Unmounted PVs") refers to the resources used by PersistentVolumes that aren't mounted to a pod using a PVC, and thus cannot be allocated to a pod.
Allocation data for today unaggregated:
Allocation data for last week, per day, aggregated by cluster:
Allocation data for the last 30 days, aggregated by the "app" label, sharing idle allocation, sharing allocations from two namespaces, sharing $100/mo in overhead, and accumulated into one allocation for the entire window:
Allocation data for 2021-03-10T00:00:00 to 2021-03-11T00:00:00 (i.e. 24h), multi-aggregated by namespace and the "app" label, filtering by properties.cluster == "cluster-one", and accumulated into one allocation for the entire window.
Allocation data for today, aggregated by annotation. See Enabling Annotation Emission to enable annotations.
/summary endpoint to view condensed payload per line item/summary is an optional API endpoint which can be added to your Allocation query via .../model/allocation/summary?window=... to provide a condensed list of your cost metrics per line item. Instead of returning the full list of schema values listed above, your query will return something like:
/topline endpoint to view cost totals across query (Aggregator only)/topline is an optional API endpoint which can be added to your /summary Allocation query via .../model/allocation/summary/topline?window=... to provide a condensed overview of your total cost metrics including all line items sampled. You will receive a single list which sums the values per all items queried, formatted similar to a regular /summary query, where numResults displays the total number of items sampled. Idle costs still need to be configured separately.
Both the reconcile and shareTenancyCosts flags start processes that distribute the costs of Assets to Allocations related to them. For the reconcile flag, these connections can be straightforward like the connection between a node Asset and an Allocation where the CPU, GPU, and RAM usage can be used to distribute a proportion of the node's cost to the Allocations that run on it. For Assets and Allocations where the connection is less well-defined, such as network Assets we have opted for a method of distributing the cost that we call Distribution by Usage Hours.
Distribution by Usage Hours takes the usage of the windows (start time and end time) of an Asset and all the Allocations connected to it and finds the number of hours that both the Allocation and Asset were running. The number of hours for each Allocation related to an Asset is called Alloc_Usage_Hours. The sum of all Alloc_Usage_Hours for a single Assets is Total_Usage_Hours. With these values, an Assets cost is distributed to each connected Allocation using the formula Asset_Cost * Alloc_Usage_Hours/Total_Usage_Hours. Depending on the Asset type an Allocation can receive proportions of multiple Asset Costs.
Asset types that use this distribution method include:
Network (reconcile): When the network pod is not enabled cost is distributed by usage hours. If the network pod is enabled cost is distributed to Allocations proportionally to usage.
Load Balancer (reconcile)
Cluster Management (shareTenancyCosts)
Attached disks (shareTenancyCosts): Does not include PVs, which are handled by reconcile
Querying on-demand with high resolution for long windows can cause serious Prometheus performance issues, including OOM errors. Start with short windows (1d or less) and proceed with caution.
Computing allocation data on-demand allows for greater flexibility with respect to step size and accuracy-versus-performance. (See resolution and error bounds for details.) Unlike the standard endpoint, which can only serve results from precomputed sets with predefined step sizes (e.g. 24h aligned to the UTC time zone), asking for a "7d" query will almost certainly result in 8 sets, including "today" and the final set, which might span 6.5d-7.5d ago. With this endpoint, however, you will be computing everything on-demand, so "7d" will return exactly seven days of data, starting at the moment the query is received. (You can still use window keywords like "today" and "lastweek", of course, which should align perfectly with the same queries of the standard ETL-driven endpoint.)
Additionally, unlike the standard endpoint, querying on-demand will not use reconciled asset costs. Therefore, the results returned will show all adjustments (e.g. CPU, GPU, RAM) to be 0.
GET http://<kubecost>/model/allocation/compute
Allocation data for the last 60m, in steps of 10m, with resolution 1m, aggregated by cluster.
Allocation data for the last 9d, in steps of 3d, with a 10m resolution, aggregated by namespace.
Tuning the resolution parameter allows the querier to make tradeoffs between accuracy and performance. For long-running pods (>1d) resolution can be tuned aggressively low (>10m) with relatively little effect on accuracy. However, even modestly low resolutions (5m) can result in significant accuracy degradation for short-running pods (<1h).
Here, we provide theoretical error bounds for different resolution values given pods of differing running durations. The tuple represents lower- and upper-bounds for accuracy as a percentage of the actual value. For example:
1.00, 1.00 means that results should always be accurate to less than 0.5% error
0.83, 1.00 means that results should never be high by more than 0.5% error, but could be low by as much as 17% error
-1.00, 10.00 means that the result could be as high as 1000% error (e.g. 30s pod being counted for 5m) or the pod could be missed altogether, i.e. -100% error.
While using Thanos, data can delayed from 1 to 3 hours, which may result in allocation queries retrieving inaccurate or incomplete data when using short window intervals. Avoid using values for window smaller than 5h as a best practice.
Note: This feature is in a beta state. It has limitations. Please read the documentation carefully.
Note: This feature is only officially supported on Kubecost Enterprise plans.
The Cost Events Audit API aims to offer improved visibility on recent changes at cluster level and their estimated cost impact.
GET http://<your-kubecost-address>/model/audit/events
Accesses the most recent cluster events and their predicted cost impact
| Name | Type | Description |
|---|---|---|
This API is disabled by default. It needs to be manually enabled first through Helm, using the following parameters:
You can also enable the Cost Events Audit API by setting the COST_EVENTS_AUDIT_ENABLED environment variable to true.
Changes at cluster level can range from actions triggered by declarative statements submitted by users (e.g. creation of a Deployment) to automated actions (e.g. cluster autoscaling) or performance events. We detect changes that would have an impact on the overall cluster cost using watchers on the Kubernetes API client.
The watchers are tracking change events across all namespaces within the local/primary cluster (the cluster that the instance of Kubecost you are interacting with via HTTP is running on).
Deployment creation
Deployment deletion
StatefulSet creation
StatefulSet deletion
Cost implications of cluster events are handled by passing the Kubernetes spec inferred from the change event to the Kubecost Predict API.
The Cost Events Audit API can return up to 1000 of the most recent cluster events. There is no time expiration limit on the events.
Events returned by the Cost Events Audit API are currently not persisted between Kubecost pod restarts.
The Cost Events Audit API does not track events for clusters other than the local/primary cluster.
Kubecost emits events when certain things happen. Those events are also recorded in an event log in the interest of diagnosing problems.
GET http://<your-kubecost-address>/model/etl/log
Accesses the most recent events in the event log
| Name | Type | Description |
|---|---|---|
All event kinds below will appear in the body of the output by default. You can filter for specific event kinds using the kind parameter. For example, to see only AllocationSetSaved in the output, your endpoint will look like:
You can also view all substrings between Allocations or Assets. For example, the following endpoint will retrieve all event kinds beginning with AssetSet:
Allocation outputs should be interpreted as:
AllocationSetSaved describes a saved AllocationSet
AllocationSetLoaded describes a loaded AllocationSet
AllocationSetAggregated describes aggregating an AllocationSet
AllocationSetTotaled describes totaling an AllocationSet
AllocationSetReconciled describes reconciling an AllocationSet
AllocationSetComputeError describes an error in computation
AllocationSetReconcileError describes an error in reconciliation
Assets outputs should be interepreted as:
AssetSetSaved describes a saved AssetSet
AssetSetLoaded describes a loaded AssetSet
AssetSetAggregated describes aggregating an AssetSet
AssetSetTotaled describes totaling an AssetSet
AssetSetReconciled describes reconciling an AssetSet
AssetSetComputeError describes an error in computation
AssetSetReconcileError describes an error in reconciliation
Underneath each event kind, you should see size and/or window returned, which are:
size: number of records in the set
window: window of the set
This log will additionally be appended to bug reports.
POST http://<your-kubecost-address>/model/prediction/speccost
The Predict API takes Kubernetes API objects ("workloads") as input and produces a cost impact prediction for them, including a diff if a matching existing workload can be found in the cluster.
| Name | Type | Description |
|---|---|---|
The API requires that workloads be passed in the request body in YAML or JSON format. If using YAML, multiple workloads can be passed via separation with the standard --- syntax. If using JSON, multiple workloads can be passed via the standard "list" format used by Kubernetes (e.g. kubectl get deployment -A -o json).
Currently supported workload types:
Deployments
StatefulSets
Pods
Write some Kubernetes specs to a file called /tmp/testspecs.yaml:
Call the endpoint with cURL, passing the file in the request body:
The output will be broken down into three primary categories:
costBefore: Represents the current monthly cost. This will be 0 if the deployment is not currently running.
costAfter: The monthly cost after the change is applied.
costChange: The difference between the values of costBefore and costAfter. If the value of costBefore was 0, then costChange should be equal to costAfter.
Observe how defaultNamespace impacts the default-deployment workload.
From that output, costChangenotices the existing kubecost-cost-analyzer deployment in the kubecost namespace and is producing an estimated negative cost difference because the request is being reduced. However, because historical usage is also factored in, there is no drastic cost reduction that might be initially expected from a 1m CPU and 1Mi memory request.
The Budget API allows you to create, update, and delete recurring budget rules to control your Kubernetes spending. Weekly and monthly budgets can be established on namespaces, clusters, and labels to set limits on cost spend, with the option to configure alerts for reaching specified budget thresholds via email, Slack, or Microsoft Teams.
POST http://<your-kubecost-address>/model/budget
Creates a recurring budget rule or updates a recurring budget rule when provided the ID of the existing rule.
| Name | Type | Description |
|---|---|---|
GET http://<your-kubecost-address>/model/budgets
Lists all existing recurring budget rules
DELETE https://<your-kubecost-address>/model/deleteBudget
Deletes a budget rule defined by id
Creating and updating recurring budget rules uses POST requests, which will require submitting a JSON object in the body of your request instead of adding parameters directly into the path (such as when deleting a recurring budget rule). See the Examples section below for more information on formatting your requests.
id parameterThe id parameter when using the endpoint /budget is considered optional, but its use will vary depending on whether you want to create or update a budget rule.
When creating a new budget rule, id should not be used. An ID for the budget rule will then be randomly generated in the response. When updating an existing budget rule, id needs to be used to identify which budget rule you want to modify, even if you only have one existing rule.
The id value of your recurring budget is needed to update or delete it. If you don't have the id value saved, you can retrieve it using /budgets, which will generate all existing budgets and their respective id values.
You can configure greater visibility towards tracking your budgets using the actions parameter, which will allow you to create alerts for when your budget spend has passed a specified percentage threshold, and send those alerts to you or your team via email, Slack, or Microsoft Teams.
When providing values for actions, percentage refers to the percentage of spendLimit which will result in an alert. For example, if "spendLimit": 2000 is configured for a weekly budget rule and "percentage": 50 is configured, an alert will be sent to all listed emails/webhooks if spending surpasses $1000 USD for the week.
The spendLimit parameter will always be determined using your configured currency type. You can manually change your currency type in Kubecost by selecting Settings, then scrolling to Currency and selecting your desired currency from the dropdown (remember to confirm your choice by selecting Save at the bottom of the page).
Kubecost does not convert spending costs to other currency types; it will only change the symbol displayed in the UI next to costs. For best results, configure your currency to what matches your spend.
Create a recurring budget rule for my test cluster which resets every Wednesday with a budget of $100.00 USD, and will send an alert via email when spending has exceeded 75% of the spend limit.
Create a recurring budget rule for my kubecost namespace which resets on the 1st of every month with a budget of $400.00 USD, and will send an alert via Slack and Microsoft Teams when spending has exceeded $100.00 of the spend limit.
GET http://<kubecost-address>/model/savings/requestSizingV2
The container request right sizing recommendation API provides recommendations for based on configurable parameters and estimates the savings from implementing those recommendations on a per-container, per-controller level. If the cluster-level resources stay static, then there may not be significant savings from applying Kubecost's recommendations until you reduce your cluster resources. Instead, your idle allocation will increase.
| Name | Type | Description |
|---|
/topline endpoint to view cost totals across query (Aggregator only)/topline is an optional API endpoint which can be added to your right-sizing query via .../savings/RequestSizingV2/topline... to provide a condensed overview of all items sampled. TotalMonthlySavings is the total estimated savings value from adopting right-sizing recommendations. Count refers to the number of items sampled. Recommendations should return null, as it is unable to provide a universal right-sizing recommendation.
The "base" recommendation is calculated from the observed usage of each resource per unique container spec (e.g. a 2-replica, 3-container deployment will have 3 recommendations: one for each container spec).
Say you have a single-container deployment with two replicas: A and B.
A's container had peak usages of 120 mCPU and 300 MiB of RAM.
B's container had peak usages of 800 mCPU and 120 MiB of RAM.
The max algorithm recommendation for the deployment's container will be 800 mCPU and 300 MiB of RAM. Overhead will be added to the base recommendation according to the target utilization parameters as described above.
| Endpoint | Brief description |
|---|---|
| API Name | UI Equivalent |
|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| CostMetric value | Description |
|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Field | Description |
|---|---|
| Name | Type | Description |
|---|---|---|
| resolution | 30s pod | 5m pod | 1h pod | 1d pod | 7d pod |
|---|---|---|---|---|---|
| Name | Type | Description |
|---|---|---|
After providing you with right sizing recommendations, Kubecost can additionally directly implement these recommendations into your environment. For more information, see the doc.
See .
window*
string
Duration of time over which to query. Compares cost usage of window to cost usage window of equal size directly preceding it. Accepts all standard Kubecost window formats (See our doc on using the window parameter).
aggregate
string
Field by which to aggregate the results. Accepts: cluster, namespace, controllerKind, controller, service, node, pod, label:<name>, and annotation:<name>. Also accepts comma-separated lists for multi-aggregation, like namespace,label:app.
accumulate
boolean
When set to false, returns daily time series data vs. cumulative data. Default is true.
external
string
If true, include external costs in each allocation. Default is false.
idle
boolean
If true, include idle cost (i.e. the cost of the un-allocated assets) as its own allocation. Default is true.
filterNamespaces
string
Comma-separated list of namespaces to match; e.g. namespace-one,namespace-two will return results from only those two namespaces.
shareIdle
boolean
If true, idle cost is allocated proportionally across all non-idle allocations, per-resource. That is, idle CPU cost is shared with each non-idle allocation's CPU cost, according to the percentage of the total CPU cost represented. Default is false.
shareNamespaces
string
Comma-separated list of namespaces to share; e.g. kube-system, kubecost will share the costs of those two namespaces with the remaining non-idle, unshared allocations.
shareLabels
string
Comma-separated list of labels to share; e.g. env:staging, app:test will share the costs of those two label values with the remaining non-idle, unshared allocations.
shareCost
float
Floating-point value representing a monthly cost to share with the remaining non-idle, unshared allocations; e.g. 30.42 ($1.00/day == $30.42/month) for the query yesterday (1 day) will split and distribute exactly $1.00 across the allocations. Default is 0.0.
shareTenancyCosts
boolean
If true, share the cost of cluster overhead assets such as cluster management costs and node attached volumes across tenants of those resources. Results are added to the sharedCost field. Both cluster management and attached volumes are shared by cluster. Default is true.
idleByNode
boolean
If true, idle allocations are created on a per node basis, which will result in different values when shared and more idle allocations when split. Default is false.
splitIdle
boolean
If true, and shareIdle == false, idle allocations are created on a per cluster or per node basis rather than being aggregated into a single idle allocation. Default is false.
reconcile
boolean
If true, pulls data from the Assets cache and corrects prices of Allocations according to their related Assets. The corrections from this process are stored in each cost categories cost adjustment field. If the integration with your cloud provider's billing data has been set up, this will result in the most accurate costs for Allocations. Default is true.
step
string
Duration of a single allocation set. If unspecified, this defaults to the window, so that you receive exactly one set for the entire window. If specified, it works chronologically backward, querying in durations of step until the full window is covered.
window*
string
Duration of time over which to query. Compares cost usage of window to cost usage window of equal size directly preceding it. Accepts all standard Kubecost window formats (See our doc on using the window parameter).
names*
string
Determines order sequence of queried items via comma-separated list. Dependent on the value of aggregate to list items. See more below.
aggregate
string
Field by which to aggregate the results. Accepts: cluster, namespace, controllerKind, controller, service, node, pod, label:<name>, and annotation:<name>. Also accepts comma-separated lists for multi-aggregation, like namespace,label:app.
accumulate
boolean
When set to false, returns daily time series data vs. cumulative data. Default is true.
external
string
If true, include external costs in each allocation. Default is false.
idle
boolean
If true, include idle cost (i.e. the cost of the un-allocated assets) as its own allocation. Default is true.
filterNamespaces
string
Comma-separated list of namespaces to match; e.g. namespace-one,namespace-two will return results from only those two namespaces.
shareIdle
boolean
If true, idle cost is allocated proportionally across all non-idle allocations, per-resource. That is, idle CPU cost is shared with each non-idle allocation's CPU cost, according to the percentage of the total CPU cost represented. Default is false.
shareNamespaces
string
Comma-separated list of namespaces to share; e.g. kube-system, kubecost will share the costs of those two namespaces with the remaining non-idle, unshared allocations.
shareLabels
string
Comma-separated list of labels to share; e.g. env:staging, app:test will share the costs of those two label values with the remaining non-idle, unshared allocations.
shareCost
float
Floating-point value representing a monthly cost to share with the remaining non-idle, unshared allocations; e.g. 30.42 ($1.00/day == $30.42/month) for the query yesterday (1 day) will split and distribute exactly $1.00 across the allocations. Default is 0.0.
shareTenancyCosts
boolean
If true, share the cost of cluster overhead assets such as cluster management costs and node attached volumes across tenants of those resources. Results are added to the sharedCost field. Both cluster management and attached volumes are shared by cluster. Default is true.
idleByNode
boolean
If true, idle allocations are created on a per node basis, which will result in different values when shared and more idle allocations when split. Default is false.
splitIdle
boolean
If true, and shareIdle == false, idle allocations are created on a per cluster or per node basis rather than being aggregated into a single idle allocation. Default is false.
reconcile
boolean
If true, pulls data from the Assets cache and corrects prices of Allocations according to their related Assets. The corrections from this process are stored in each cost categories cost adjustment field. If the integration with your cloud provider's billing data has been set up, this will result in the most accurate costs for Allocations. Default is true.
before*
String
Duration in time of the past. Supports hours or days before the current time in the following format: 2h or 3d. See the Allocation API documentation for more a more detailed explanation of valid inputs to window. Important note: before must be further in the past than after (e.g. after=1d, before=1d offset 1d)
after*
String
Duration in time closest to now. Supports hours or days before the current time in the following format: 2h or 3d. See the Allocation API documentation for more a more detailed explanation of valid inputs to window. Important note: after must be closer to now than before (e.g. before=1d offset 7d, after=1d offset 3d)
costChangeRatio
float64
Changes the ratio of cost changes when displaying 'Changed' types. e.g. costChangeRatio=0.1 will display all assets that had a cost change of 0.1 (10%) or more. Defaults to 0.05 (5%).
aggregate
String
Used to consolidate cost model data. Passing an empty value for this parameter, or not passing one at all, returns data by an individual asset.
filterClusters
String
Comma-separated list of clusters to match; e.g. cluster-one,cluster-two will return results from only those two clusters.
filterNodes
String
Comma-separated list of nodes to match; e.g. node-one,node-two will return results from only those two nodes.
filterNamespaces
String
Comma-separated list of namespaces to match; e.g. namespace-one,namespace-two will return results from only those two namespaces.
filterLabels
String
Comma-separated list of annotations to match; e.g. app:cost-analyzer, app:prometheus will return results with either of those two label key-value-pairs.
filterServices
String
Comma-separated list of services to match; e.g. frontend-one,frontend-two will return results from only those two services.
filterControllerKinds
String
Comma-separated list of controller kinds to match; e.g. deployment,job will return results with only those two controller kinds.
filterControllers
String
Comma-separated list of controllers to match; e.g. deployment-one,statefulset-two will return results from only those two controllers.
filterPods
String
Comma-separated list of pods to match; e.g. pod-one,pod-two will return results from only those two pods.
filterAnnotations
String
Comma-separated list of annotations to match; e.g. name:annotation-one,name:annotation-two will return results with either of those two annotation key-value-pairs.
filterContainers
String
Comma-separated list of containers to match; e.g. container-one,container-two will return results from only those containers.
window*
String
Window of the query. Only accepts daily intervals, example window=3d.
costMetric
String
Determines which cloud cost metric type will be returned. Acceptable values are AmortizedNetCost, InvoicedCost, ListCost, and NetCost. Default is AmortizedNetCost.
aggregate
String
Field by which to aggregate the results. Accepts: invoiceEntityID, accountID, provider, service, and label:<name>. Supports multi-aggregation using comma-separated lists. Example: aggregate=accountID,service
filterInvoiceEntityIDs
String
Filter for account
filterAccountIDs
String
GCP only, filter for projectID
filterProviders
String
Filter for cloud service provider
filterProvidersID
String
Filter for resource-level ID given by CSP
filterServices
String
Filter for cloud service
filterCategories
String
Filter based on object type
filterLabels
String
Filter for a specific label. Does not support filtering for multiple labels at once.
window*
string
Window of the query. Accepts all standard Kubecost window formats (See our doc on using the window parameter).
aggregate
string
Field by which to aggregate the results. Accepts: invoiceEntityID, accountID, provider, service, and label:<name>. Supports multi-aggregation using comma-separated lists. Example: aggregate=accountID,service
filterInvoiceEntityIDs
string
Filter for account
filterAccountIDs
string
GCP only, filter for projectID
filterProviders
string
Filter for cloud service provider
filterServices
string
Filter for cloud service
filterLabel
String
Filter for a specific label. Does not support filtering for multiple labels at once.
NetCost
Costs inclusive of discounts and credits. Will also include one-time and recurring charges.
AmortizedNetCost
NetCost with removed cash upfront fees and amortized
ListCost
CSP pricing without any discounts
InvoicedCost
Pricing based on usage during billing period
/savings
Provides cluster-level potential savings estimates based on specific savings opportunities available in other endpoints.
Provides recommendations for sizing clusters (node types and quantities).
Provides recommendations for setting container resource requests.
List abandoned workloads based on network traffic.
Applies Kubecost's container request recommendations to your cluster.
/projectDisks
List orphaned disks.
/projectAddresses
List orphaned IP addresses.
Allocation API
Allocation/Cloud Cost Explorer Trends API
Allocations/Cloud Cost Explorer dashboards, Total cost column percentage
Assets API
Cloud Cost API
Budget API
Cost Events Audit API
Predict API
Savings API
Cluster Right Sizing Recommendation API
Container Request Right Sizing Recommendation API
Abandoned Workloads API
commit*
boolean
Flag that acts as a safety precaution. These can be long-running processes so this endpoint should not be run arbitrarily. true will restart the process.
provider
string
Optional parameter for the ProviderKey of your CSP. If included, only the specified Cloud Store will run the operation. If not included, all Cloud Stores in the ETL will run the operation.
window*
String
The applicable window for repair by the Cloud Store. See Using window parameter for more details.
provider
string
Optional parameter for the ProviderKey of your CSP. If included, only the specified Cloud Store will run the operation. If not included, all Cloud Stores in the ETL will run the operation.
commit*
boolean
Flag that acts as a safety precaution. These can be long-running processes so this endpoint should not be run arbitrarily. true will restart the process.
provider
String
Optional parameter for the ProviderKey of your CSP. If included, only the specified Cloud Store will run the operation. If not included, all Cloud Stores in the ETL will run the operation.
window*
string
The applicable window for repair by the Cloud Store. See Using window parameter for more details.
provider
string
Optional parameter for the ProviderKey of your CSP. If included, only the specified Cloud Store will run the operation. If not included, all Cloud Stores in the ETL will run the operation.
window*
string
Duration of time over which to query. Compares cost usage of window to cost usage window of equal size directly preceding it. Accepts all standard Kubecost window formats (See our doc on using the window parameter).
names*
string
Determines order sequence of queried items via comma-separated list. Dependent on the value of aggregate to list items. See more below.
aggregate
string
Field by which to aggregate the results. Accepts: invoiceEntityID, accountID, provider, service, and label:<name>. Supports multi-aggregation using comma-separated lists, such as aggregate=accountID,service. When no value is provided, the query will aggregate by individual items.
accumulate
boolean
When set to false, returns daily time series data vs. cumulative data. Default is true.
CostMetricName
string
Determines which cloud cost metric type will be returned. Acceptable values are AmortizedNetCost, InvoicedCost, ListCost, and NetCost. Default is AmortizedNetCost.
filter
string
Filter your results by a particular category or value. For example, when to only see trends in AWS spend, set this parameter to filter=provider:"AWS". Supports Filter Parameters (v2) language.
window*
string
Duration of time over which to query. Accepts words like today, week, month, yesterday, lastweek, lastmonth; durations like 30m, 12h, 7d; comma-separated RFC3339 date pairs like 2021-01-02T15:04:05Z,2021-02-02T15:04:05Z; comma-separated Unix timestamp (seconds) pairs like 1578002645,1580681045.
aggregate
string
Field by which to aggregate the results. Accepts: cluster, namespace, controllerKind, controller, service, node, pod, label:<name>, and annotation:<name>. Also accepts comma-separated lists for multi-aggregation, like namespace,label:app.
accumulate
boolean
If true, sum the entire range of sets into a single set. Default value is false.
idle
boolean
If true, include idle cost (i.e. the cost of the un-allocated assets) as its own allocation. (See special types of allocation.) Default is true.
external
boolean
If true, include external, or out-of-cluster costs in each allocation. Default is false.
filterClusters
string
Comma-separated list of clusters to match; e.g. cluster-one,cluster-two will return results from only those two clusters.
filterNodes
string
Comma-separated list of nodes to match; e.g. node-one,node-two will return results from only those two nodes.
filterNamespaces
string
Comma-separated list of namespaces to match; e.g. namespace-one,namespace-two will return results from only those two namespaces.
filterControllerKinds
string
Comma-separated list of controller kinds to match; e.g. deployment, job will return results with only those two controller kinds.
filterControllers
string
Comma-separated list of controllers to match; e.g. deployment-one,statefulset-two will return results from only those two controllers.
filterPods
string
Comma-separated list of pods to match; e.g. pod-one,pod-two will return results from only those two pods.
filterAnnotations
string
Comma-separated list of annotations to match; e.g. name:annotation-one,name:annotation-two will return results with either of those two annotation key-value-pairs.
filterLabels
string
Comma-separated list of annotations to match; e.g. app:cost-analyzer, app:prometheus will return results with either of those two label key-value-pairs.
filterServices
string
Comma-separated list of services to match; e.g. frontend-one,frontend-two will return results with either of those two services.
format
string
Set to csv to download an accumulated version of the allocation results in CSV format. Set to pdf to download an accumulated version of the allocation results in PDF format. By default, results will be in JSON format.
costUnit
string
Cost metric format. Learn about cost metric calculations in our Allocations Dashboard doc. Supports cumulative, hourly, daily, and monthly. Default is cumulative.
shareIdle
boolean
If true, idle cost is allocated proportionally across all non-idle allocations, per-resource. That is, idle CPU cost is shared with each non-idle allocation's CPU cost, according to the percentage of the total CPU cost represented. Default is false.
splitIdle
boolean
If true, and shareIdle == false, Idle Allocations are created on a per cluster or per node basis rather than being aggregated into a single "idle" allocation. Default is false.
idleByNode
boolean
If true, idle allocations are created on a per node basis. Which will result in different values when shared and more idle allocations when split. Default is false.
includeSharedCostBreakdown
boolean
Provides breakdown of cost metrics for any shared resources. Default is true.
reconcile
boolean
If true, pulls data from the Assets cache and corrects prices of Allocations according to their related Assets. The corrections from this process are stored in each cost category's cost adjustment field. If the integration with your cloud provider's billing data has been set up, this will result in the most accurate costs for Allocations. Default is true.
shareTenancyCosts
boolean
If true, share the cost of cluster overhead assets such as cluster management costs and node attached volumes across tenants of those resources. Results are added to the sharedCost field. As of v1.93.0 both cluster management and attached volumes are shared by cluster. Default is true.
shareNamespaces
string
Comma-separated list of namespaces to share; e.g. kube-system, kubecost will share the costs of those two namespaces with the remaining non-idle, unshared allocations.
shareLabels
string
Comma-separated list of labels to share; e.g. env:staging, app:test will share the costs of those two label values with the remaining non-idle, unshared allocations.
shareCost
float
Floating-point value representing a monthly cost to share with the remaining non-idle, unshared allocations; e.g. 30.42 ($1.00/day == $30.42/month) for the query yesterday (1 day) will split and distribute exactly $1.00 across the allocations. Default is 0.0.
shareSplit
string
Determines how to split shared costs among non-idle, unshared allocations. By default, the split will be weighted; i.e. proportional to the cost of the allocation, relative to the total. The other option is even; i.e. each allocation gets an equal portion of the shared cost. Default is weighted.
step
string
Duration of each individual data metric across the window. Accepts 1h, 1d, or 1w. If left blank, defaults to longest step duration based on level of granularity of data represented by window.
window*
string
Duration of time over which to query. Accepts words like today, week, month, yesterday, lastweek, lastmonth; durations like 30m, 12h, 7d; comma-separated RFC3339 date pairs like 2021-01-02T15:04:05Z,2021-02-02T15:04:05Z; comma-separated Unix timestamp (seconds) pairs like 1578002645,1580681045.
aggregate
string
Field by which to aggregate the results. Accepts: cluster, namespace, controllerKind, controller, service, node, pod, label:<name>, and annotation:<name>. Also accepts comma-separated lists for multi-aggregation, like namespace,label:app.
accumulate
string
If true, sum the entire range of time intervals into a single set. Default value is false. Also supports accumulation by specific intervals of time including hour, day, and week. Does not accumulate idle costs, which must be configured separately.
idle
boolean
If true, include idle cost (i.e. the cost of the un-allocated assets) as its own allocation. (See special types of allocation.) Default is true.
external
boolean
If true, include external, or out-of-cluster costs in each allocation. Default is false.
offset
int
Refers to the number of pages you are searching through which will increase by integers for the amount of pages you want to skip. Starting value is 0, representing the first page of results.
limit
int
Refers to the number of line items per page. Pair with the offset parameter to filter your payload to specific sections of line items. You should also set accumulate=true to obtain a single list of line items, otherwise you will receive a group of line items per interval of time being sampled.
filter
string
Filter your results by any category which you can aggregate by, can support multiple filterable items in the same category in a comma-separated list. For example, to filter results by clusters A and B, use filter=cluster:clusterA,clusterB See our Filter Parameters doc for a complete explanation of how to use filters and what categories are supported.
format
string
Set to csv to download an accumulated version of the allocation results in CSV format. Set to pdf to download an accumulated version of the allocation results in PDF format. By default, results will be in JSON format.
format
string
Cost metric format. Learn about cost metric calculations in our Allocations Dashboard doc. Supports cumulative, hourly, daily, and monthly. Default is cumulative.
shareIdle
boolean
If true, idle cost is allocated proportionally across all non-idle allocations, per-resource. That is, idle CPU cost is shared with each non-idle allocation's CPU cost, according to the percentage of the total CPU cost represented. Default is false.
splitIdle
boolean
If true, and shareIdle == false, Idle Allocations are created on a per cluster or per node basis rather than being aggregated into a single "idle" allocation. Default is false.
idleByNode
boolean
If true, idle allocations are created on a per node basis. Which will result in different values when shared and more idle allocations when split. Default is false.
includeSharedCostBreakdown
boolean
Provides breakdown of cost metrics for any shared resources. Default is true.
reconcile
boolean
If true, pulls data from the Assets cache and corrects prices of Allocations according to their related Assets. The corrections from this process are stored in each cost category's cost adjustment field. If the integration with your cloud provider's billing data has been set up, this will result in the most accurate costs for Allocations. Default is true.
shareTenancyCosts
boolean
If true, share the cost of cluster overhead assets such as cluster management costs and node attached volumes across tenants of those resources. Results are added to the sharedCost field. As of v1.93.0 both cluster management and attached volumes are shared by cluster. Default is true.
shareNamespaces
string
Comma-separated list of namespaces to share; e.g. kube-system, kubecost will share the costs of those two namespaces with the remaining non-idle, unshared allocations.
shareLabels
string
Comma-separated list of labels to share; e.g. env:staging, app:test will share the costs of those two label values with the remaining non-idle, unshared allocations.
shareCost
float
Floating-point value representing a monthly cost to share with the remaining non-idle, unshared allocations; e.g. 30.42 ($1.00/day == $30.42/month) for the query yesterday (1 day) will split and distribute exactly $1.00 across the allocations. Default is 0.0.
shareSplit
string
Determines how to split shared costs among non-idle, unshared allocations. By default, the split will be weighted; i.e. proportional to the cost of the allocation, relative to the total. The other option is even; i.e. each allocation gets an equal portion of the shared cost. Default is weighted.
name
Name of each relevant Kubernetes concept described by the allocation, delimited by slashes, e.g. "cluster/node/namespace/pod/container"
properties
Map of name-to-value for all relevant property fields, including: cluster, node, namespace, controller, controllerKind, pod, container, labels, annotation, etc. Note: Prometheus only supports underscores (_) in label names. Dashes (-) and dots (.), while supported by Kubernetes, will be translated to underscores by Prometheus. This may cause the merging of labels, which could result in aggregated costs being charged to a single label.
window
Period of time over which the allocation is defined.
start
Precise starting time of the allocation. By definition must be within the window.
end
Precise ending time of the allocation. By definition must be within the window.
minutes
Number of minutes running; i.e. the minutes from start until end.
cpuCores
Average number of CPU cores allocated while running.
cpuCoreRequestAverage
Average number of CPU cores requested while running.
cpuCoreUsageAverage
Average number of CPU cores used while running.
cpuCoreHours
Cumulative CPU core-hours allocated.
cpuCost
Cumulative cost of allocated CPU core-hours.
cpuCostAdjustment
Change in cost after allocated CPUs have been reconciled with updated node cost
cpuEfficiency
Ratio of cpuCoreUsageAverage-to-cpuCoreRequestAverage, meant to represent the fraction of requested resources that were used.
gpuCount
Number of GPUs allocated to the workload.
gpuHours
Cumulative GPU-hours allocated.
gpuCost
Cumulative cost of allocated GPU-hours.
gpuCostAdjustment
Change in cost after allocated GPUs have been reconciled with updated node cost
networkTransferBytes
Total bytes sent from the workload
networkReceiveBytes
Total bytes received by the workload
networkCost
Cumulative cost of network usage.
networkCrossZoneCost
Cumulative cost of Cross-zone network egress usage.
networkCrossRegionCost
Cumulative cost of Cross-region network egress usage.
networkInternetCost
Cumulative cost of internet egress usage.
networkCostAdjustment
Updated network cost
loadBalancerCost
Cumulative cost of allocated load balancers.
loadBalancerCostAdjustment
Updated load balancer cost.
pvBytes
Average number of bytes of PersistentVolumes allocated while running.
pvByteHours
Cumulative PersistentVolume byte-hours allocated.
pvCost
Cumulative cost of allocated PersistentVolume byte-hours.
pvs
Map of PersistentVolumeClaim costs that have been allocated to the workload
pvCostAdjustment
Updated persistent volume cost.
ramBytes
Average number of RAM bytes allocated. An allocated resource is the source of cost, according to Kubecost - regardless of if a requested resource is used.
ramByteRequestAverage
Average of the RAM requested by the workload. Requests are a Kubernetes tool for preallocating/reserving resources for a given container.
ramByteUsageAverage
Average of the RAM used by the workload. This comes from moment-to-moment measurements of live RAM byte usage of each container. This is roughly the number you see under RAM if you pull up Task Manager (Windows), top on Linux, or Activity Monitor (MacOS).
ramByteHours
Cumulative RAM byte-hours allocated.
ramCost
Cumulative cost of allocated RAM byte-hours.
ramEfficiency
Ratio of ramByteUsageAverage-to-ramByteRequestAverage, meant to represent the fraction of requested resources that were used.
sharedCost
Cumulative cost of shared resources, including shared namespaces, shared labels, shared overhead.
externalCost
Cumulative cost of external resources.
totalCost
Total cumulative cost
totalEfficiency
Cost-weighted average of cpuEfficiency and ramEfficiency. In equation form: ((cpuEfficiency * cpuCost) + (ramEfficiency * ramCost)) / (cpuCost + ramCost)
rawAllocationOnly
Object with fields cpuCoreUsageMax and ramByteUsageMax, which are the maximum usages in the window for the Allocation. If the Allocation query is aggregated or accumulated, this object will be null because the meaning of maximum is ambiguous in these situations. Consider aggregating by namespace: should the maximum be the maximum of each Allocation individually, or the maximum combined usage of all Allocations (at any point in time in the window) in the namespace?
window*
string
Duration of time over which to query. Accepts words like today, week, month, yesterday, lastweek, lastmonth; durations like 30m, 12h, 7d; RFC3339 date pairs like
2021-01-02T15:04:05Z,2021-02-02T15:04:05Z; Unix timestamps like 1578002645,1580681045.
resolution
string
Duration to use as resolution in Prometheus queries. Smaller values (i.e. higher resolutions) will provide better accuracy, but worse performance (i.e. slower query time, higher memory use). Larger values (i.e. lower resolutions) will perform better, but at the expense of lower accuracy for short-running workloads. See
for details. Default is
1m
.
step
string
Duration of a single allocation set. If unspecified, this defaults to the window, so that you receive exactly one set for the entire window. If specified, it works chronologically backward, querying in durations of step until the full window is covered.
aggregate
string
Field by which to aggregate the results. Accepts: cluster, namespace,controllerKind, controller, service, label:<name>, and annotation:<name>. Also accepts comma-separated lists for multi-aggregation, like namespace,label:app.
accumulate
boolean
If true, sum the entire range of sets into a single set. Default value is false.
1m
-1.00, 2.00
0.80, 1.00
0.98, 1.00
1.00, 1.00
1.00, 1.00
2m
-1.00, 4.00
0.80, 1.20
0.97, 1.00
1.00, 1.00
1.00, 1.00
5m
-1.00, 10.00
-1.00, 1.00
0.92, 1.00
1.00, 1.00
1.00, 1.00
10m
-1.00, 20.00
-1.00, 2.00
0.83, 1.00
0.99, 1.00
1.00, 1.00
30m
-1.00, 60.00
-1.00, 6.00
0.50, 1.00
0.98, 1.00
1.00, 1.00
60m
-1.00, 120.00
-1.00, 12.00
-1.00, 1.00
0.96, 1.00
0.99, 1.00
count
int
Number of events to return. If unspecified, it returns all events available.
filterNamespaces
string
Comma-separated list of namespaces to match; e.g. namespace-one,namespace-two will return change events that have occurred only in those two namespaces.
filterEventTypes
string
Filter query by event type. Currently, only add and delete are accepted. (more types coming soon) Also accepts comma-separated lists, like add,delete.
filterResourceTypes
string
Resource type. Currently, only deployment is accepted. (more types coming soon)
filterTotalCostLowerBound
float
Floating-point value representing the lower bound for the total event cost.
filterTotalCostUpperBound
float
Floating-point value representing the upper bound for the total event cost.
window
string
Duration of time over which to query. Accepts all standard Kubecost window formats (See our docs on using the window parameter).
kind
string
Filter query by event kind (see below).
clusterID*
string
The Kubecost cluster ID of the cluster in which the workloads will be deployed. Currently, this must be the same as the cluster ID of the Kubecost installation which is serving the /speccost endpoint. Support for multi-cluster is planned.
defaultNamespace*
string
The namespace in which namespace-scoped objects will be "deployed" to if no namespace is set in the standard metadata field of the object.
window
string
The Kubecost data window used for determining resource costs fed into the cost prediction. Accepts all standard Kubecost window formats (See our doc on using the window parameter). Default is 2d.
noUsage
boolean
Set to true to ignore historical usage data (if it exists) when making the prediction. This is equivalent to making a prediction using only requests.
name*
string
Name of the budget rule
values*
string
Used for specifying the group and name where the budget rule is applied to in the form of a key-value pair. Accepts namespace, cluster, or label for the first value, followed by the corresponding item. For example, when applying a budget rule to a namespace named kubecost, this parameter is configured as values=namespace:kubecost.
interval*
string
The interval that the budget will reset with (either weekly or monthly).
intervalDay
int
The day the budget will reset. When interval=weekly, intervalDay is the day of the week, with intervalDay=0 for Sunday, intervalDay=1 for Monday, etc. When interval=monthly, intervalDay corresponds with the day of the month.
spendLimit*
int
The budget limit value. Currency can be configured in Settings > Cloud Cost Settings > Currency dropdown.
id
string
Only should be used when updating a budget rule; ID of the budget rule being modified. For more info, see the Using the id parameter section below.
action
string
Optional configurations for providing visibility when your budget exceeds a specified percentage threshold. This parameter can generate emails, and Slack or Microsoft Teams messages to suit your work environment. For more information, see the Using Budget Actions section below.
id*
string
ID of the recurring budget rule to be deleted
days
int
Number of historical days over which network traffic should be measured.
threshold
int
The threshold of total traffic (bytes in/out per second) at which a workload is determined abandoned.
algorithmCPU | string |
algorithmRAM | string | Like |
qCPU | float in the range (0, 1] | The desired quantile to base CPU recommendations on. Only used if |
qRAM | float in the range (0, 1] | Like |
targetCPUUtilization | float in the range (0, 1] |
targetRAMUtilization | float in the range (0, 1] | Calculated like |
minRecCPUMillicores | float | Lower bound, in millicores, of the CPU recommendation. Defaults to 10. Be careful when modifying below 10 for the following reason. Kubernetes currently recommends a maximum of 110 pods per node. A 10m minimum recommendation allows close to that (if all nodes are single core) while also being a round number. |
minRecRAMBytes | float | Lower bound, in bytes, of the RAM recommendation. Defaults to 20MiB (20 * 1024 * 1024). |
window* | string | Required parameter. Duration of time over which to calculate usage. Supports days before the current time in the following format: |
filter | string |
sortBy | string | Column to sort the response by. Defaults to |
sortByOrder | string | Order to sort by. Defaults to |
includeLabelsAndAnnotations | boolean | Displays all labels and annotations associated with each container request when set to |
The algorithm to be used to calculate CPU recommendations based on historical CPU usage data. Options are max and quantile. Max recommendations are based on the maximum-observed usage in window. Quantile recommendations are based on a quantile of observed usage in window (requires the qCPU parameter to set the desired quantile). Defaults to max. To use the quantile algorithm, the must be enabled.
A ratio of headroom on the base recommended CPU request. If the base recommendation is 100 mCPU and this parameter is 0.8, the recommended CPU request will be 100 / 0.8 = 125 mCPU. Defaults to 0.7. Inputs that fail to parse (see ) will default to 0.7.
3d. Note: Hourly windows are not currently supported. Note: It's recommended to provide a window greater than 2d. See the for more a more detailed explanation of valid inputs to window.
A filter to reduce the set of workloads for which recommendations will be calculated. See our doc for syntax. v1 filters are also supported.