Kubecost offers a number of API endpoints to query cost metrics data. The Kubecost API is especially useful in cases where you want to integrate Kubecost data with your existing services, trigger alerts, or set up automation pipelines.
The Kubecost API can be queried using the <KUBECOST_IP>:9090/model/ prefix. In order to do this, you’ll either need to expose Kubecost locally, or via an AWS Application Load Balancer (ALB). Full steps for both are described in the Deploying and Accessing Kubecost module of this lab.
For the sake of simplicity, we’ll access the API from a curl pod by running following command in our AWS Cloud9 environment terminal:
kubectl run curlpod --image=curlimages/curl -i --tty -- sh
ENDPOINT="http://kubecost-cost-analyzer.kubecost.svc.cluster.local:9090"
Here are some examples of data available in the Free Tier of the API:
/allocationThe Kubecost Allocation API is used by the Kubecost Allocation frontend and 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 to large clusters.
Example 1: Request allocation data for each 24-hour period in the last three days, aggregated by namespace by running following command in your AWS Cloud9 environment terminal:
curl $ENDPOINT/model/allocation \
-d window=3d \
-d aggregate=namespace \
-d accumulate=false \
-d shareIdle=false \
-G
Note: querying for “3d” will likely return a range of four sets because the queried range will overlap with four precomputed 24-hour sets, each aligned to the configured timezone.
Example 2:
Allocation data for the last one day, multi-aggregated by namespace and deployment, and accumulated into one allocation for the entire window.
curl $ENDPOINT/model/allocation \
-d window=1d \
-d aggregate=namespace,deployment \
-d accumulate=true \
-G
/assetsAssets API retrieves the backing cost data broken down by individual assets, e.g. node, disk, etc, and provides various aggregations of this data. Optionally provides the ability to integrate with external cloud assets.
API parameters include the following:
window dictates the applicable window for measuring historical asset cost. Currently, supported options are as follows:
aggregate is used to consolidate cost model data. Supported aggregation types are cluster and type. Passing an empty value for this parameter, or not passing one at all, returns data by an individual asset.accumulate when set to false this endpoint returns daily time series data vs cumulative data. Default value is false.disableAdjustments when set to true, zeros out all adjustments from cloud provider reconciliation, which would otherwise change the totalCost.format when set to csv, will download an accumulated version of the asset results in CSV format. By default, results will be in JSON format.This API returns a set of JSON objects in this format of following example:
curl $ENDPOINT/model/assets \
-d window=today \
-d aggregate=type \
-d accumulate=true \
-d disableAdjustments=true \
-d format=json \
-G
Example results:
{
"code": 200,
"data": [
{
"ClusterManagement": {
"type": "ClusterManagement",
"properties": {
"category": "Management",
"provider": "AWS",
"service": "Kubernetes"
},
"labels": {},
"window": {
"start": "2022-11-07T00:00:00Z",
"end": "2022-11-08T00:00:00Z"
},
"start": "2022-11-07T00:00:00Z",
"end": "2022-11-08T00:00:00Z",
"minutes": 1440,
"totalCost": 4.056748
},
"Disk": {
"type": "Disk",
"properties": {
"category": "Storage",
"provider": "AWS",
"service": "Kubernetes"
},
"labels": {},
"window": {
"start": "2022-11-07T00:00:00Z",
"end": "2022-11-08T00:00:00Z"
},
"start": "2022-11-07T00:00:00Z",
"end": "2022-11-07T20:22:00Z",
"minutes": 1222,
"byteHours": 14907798980812.8,
"bytes": 731970490056.2749,
"byteHoursUsed": 249191188022.46954,
"byteUsageMax": null,
"breakdown": {
"idle": 0.9689472045060643,
"other": 0,
"system": 0.031052795493935748,
"user": 0
},
"adjustment": 0,
"totalCost": 1.190033,
"storageClass": "",
"volumeName": "",
"claimName": "",
"claimNamespace": ""
},
"Node": {
"type": "Node",
"properties": {
"category": "Compute",
"provider": "AWS",
"service": "Kubernetes"
},
"labels": {
"label_beta_kubernetes_io_os": "linux",
"label_eks_amazonaws_com_capacityType": "ON_DEMAND",
"label_eks_amazonaws_com_sourceLaunchTemplateVersion": "1",
"label_kubernetes_io_os": "linux"
},
"window": {
"start": "2022-11-07T00:00:00Z",
"end": "2022-11-08T00:00:00Z"
},
"start": "2022-11-07T00:00:00Z",
"end": "2022-11-07T20:22:00Z",
"minutes": 1222,
"nodeType": "",
"cpuCores": 7.996727,
"ramBytes": 24359995365.18494,
"cpuCoreHours": 162.866667,
"ramByteHours": 496131905604.26666,
"GPUHours": 0,
"cpuBreakdown": {
"idle": 0.8225574364538241,
"other": 0.016029761260400448,
"system": 0.019269797625607796,
"user": 0.14214300466016733
},
"ramBreakdown": {
"idle": 0.8991634628362297,
"other": 0,
"system": 0.008285625609704916,
"user": 0.09255091155406577
},
"preemptible": 0,
"discount": 0,
"cpuCost": 3.88239,
"gpuCost": 0,
"gpuCount": 0,
"ramCost": 1.606193,
"adjustment": 0,
"totalCost": 5.488583
}
}
]
}