Cloudability Report API Documentation

Summary

The report endpoint is intended to replace many functions that were previously split across a variety of containers APIs and is intended to provide a more singular view of the data powering the containers insights feature.

This endpoint allows for analysis of data by specification of specific metrics to be aggregated which can be combined with groups and filters to gather cost.

Endpoint

/v3/containers/report

Query Parameters:

Request Body

The report request body is a json object comprised of a the following key attributes:

Supported Cost Types

Supported Metric Values

Request-able fields

Supported Widget Types

Supported Group, Count and Filter Values

Groups, Counts, and Filters share a overlapping set of accessible data, which can be utilized in the following ways:

Groups

Groups return results aggregated by unique values in that field.

For example, grouping by cluster would return a result set that is isolated by cluster.

Counts

Counts return a result section that identifies the number of unique entries for that aspect.

For example, a count of namespaces would return the total number of namespaces within the selection.

Filters

Filters allow a user to constrain the result set to only a subset of results.

For example, supplying a filter of workload_type==deployment would only return results for workloads identified as being owned by a deployment.

Using Filters

Filters can be configured by supplying the:

• Filtered Attribute

  • Any value denoted as filterable in the above list

• Operator

  • ==

    • Equals (case sensitive)

  • []=

    • One of (case sensitive)

• Filtered Value

  • Any value that the user wants to filter upon

Examples:

• namespace==kube-system

  • Will filter down results to only show data for kube-system

• workload_type[]=cronjob,job

  • Will filter down results to only show data for cronjobs or jobs

Supported Sort Configurations

If not set, the sort feature defaults to sorting by the first specified metric column in descending order. This is setup to ensure pagination is always possible.

Sort values should be passed in the order that the caller wishes them to take place, and can be specified for any requested metric value.

The example below would sort rows by efficiency in descending order, then by total_cost in descending order.

[
  {
    "sortMetric": "total_cost_efficiency",
    "sortOrder": "desc"
   },
   {
     "sortMetric": "total_cost",
     "sortOrder": "desc"
   }
 ]

Pagination

If the above data for pagination indicates that another page is available for consumption, then the value in "nextToken" can be passed back into the api via the "paginationToken" parameter.

US Example (API endpoint): https://api.cloudability.com/v3/containers/report

Example Requests

curl --location 'https://api.cloudability.com/v3/containers/report' \
--header 'apptio-opentoken: {token}' \
--header 'apptio-environmentid: {env_id}' \
--header 'Content-Type: application/json' \
--data '{
    "start": "2024-06-10",
    "end": "2024-06-10",
    "costType": "adjusted",
    "metrics": [
	"total_cost"
    ],
    "group": [
	"namespace"
    ],
    "count": [
	"workload_name"
    ],
	"filters": [
		"cluster==XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
	],
    "sort": [
	{
	     "sortMetric": "total_cost",
	     "sortOrder": "desc"
	}
    ],
    "widgetType": "top",
    "limit": 1
}'

Example response, including the pagination token that can be passed back into the api.

{
    "result": {
	"data": [
	   {
		"count": [
		    {
			"key": "workload_name",
			"value": "20"
		    }
		],
		"dimensions": {
		    "namespace": "my-namespace"
		},
		"metrics": {
		    "total_cost": {
			"unit": "currency",
			"values": [
				100.00
			]
		    }
		}
	    }
	 ],
	"pagination": {
	    "hasNext": true,
	    "nextToken": "veryLongPaginationToken"
	}
   }
}

This response body is broken into the following section: