Skip to content

Commit

Permalink
Add /assets to API with example
Browse files Browse the repository at this point in the history 
Signed-off-by: Matt Ray <github@mattray.dev>
  • Loading branch information
@mattray
mattray committed Jun 28, 2024
1 parent b2aac97 commit d568014
Show file tree
Hide file tree
Showing 2 changed files with 177 additions and 11 deletions.
153 changes: 144 additions & 9 deletions docs/integrations/api-examples.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,141 @@ curl -G http://localhost:9003/allocation/compute \
}
```

## `/assets` Example

The OpenCost `/assets` API has the `window` query parameter for retrieving the underlying asset data associated with the Kubernetes cluster.

### Last 7 days of Assets request

```sh
curl -G http://localhost:9003/assets -d window=7d
```

```json
{
"code": 200,
"status": "success",
"data": {
"GCP/__undefined__/testuser-opencost/Compute/gke-opencost/Node/Kubernetes/gke-opencost-1-default-pool-a30d4801-81dm/gke-opencost-1-default-pool-a30d4801-81dm": {
"type": "Node",
"properties": {
"category": "Compute",
"provider": "GCP",
"project": "testuser-opencost",
"service": "Kubernetes",
"cluster": "gke-opencost",
"name": "gke-opencost-1-default-pool-a30d4801-81dm",
"providerID": "gke-opencost-1-default-pool-a30d4801-81dm"
},
"labels": {
"beta_kubernetes_io_arch": "amd64",
"beta_kubernetes_io_instance_type": "e2-small",
"beta_kubernetes_io_os": "linux",
"cloud_google_com_gke_boot_disk": "pd-balanced",
"cloud_google_com_gke_container_runtime": "containerd",
"cloud_google_com_gke_cpu_scaling_level": "2",
"cloud_google_com_gke_logging_variant": "DEFAULT",
"cloud_google_com_gke_max_pods_per_node": "110",
"cloud_google_com_gke_nodepool": "default-pool",
"cloud_google_com_gke_os_distribution": "cos",
"cloud_google_com_gke_provisioning": "spot",
"cloud_google_com_gke_spot": "true",
"cloud_google_com_gke_stack_type": "IPV4",
"cloud_google_com_machine_family": "e2",
"cloud_google_com_private_node": "false",
"failure_domain_beta_kubernetes_io_region": "australia-southeast1",
"failure_domain_beta_kubernetes_io_zone": "australia-southeast1-c",
"kubernetes_io_arch": "amd64",
"kubernetes_io_hostname": "gke-opencost-1-default-pool-a30d4801-81dm",
"kubernetes_io_os": "linux",
"node_kubernetes_io_instance_type": "e2-small",
"providerID": "gce://testuser-opencost/australia-southeast1-c/gke-opencost-1-default-pool-a30d4801-81dm",
"topology_gke_io_zone": "australia-southeast1-c",
"topology_kubernetes_io_region": "australia-southeast1",
"topology_kubernetes_io_zone": "australia-southeast1-c"
},
"window": {
"start": "2024-06-22T00:00:00Z",
"end": "2024-06-29T00:00:00Z"
},
"start": "2024-06-22T00:00:00Z",
"end": "2024-06-24T18:10:00Z",
"minutes": 3970.000000,
"nodeType": "e2-small",
"pool": "default-pool",
"cpuCores": 0.500000,
"ramBytes": 2072743936.000000,
"cpuCoreHours": 33.083333,
"ramByteHours": 137146557098.666672,
"GPUHours": 0.000000,
"cpuBreakdown": {
"idle": 1,
"other": 0,
"system": 0,
"user": 0
},
"ramBreakdown": {
"idle": 1,
"other": 0,
"system": 0,
"user": 0
},
"preemptible": 1.000000,
"discount": 0.000000,
"cpuCost": 0.307185,
"gpuCost": 0.000000,
"gpuCount": 0.000000,
"ramCost": 0.158929,
"adjustment": 0.000000,
"overhead": {
"CpuOverheadFraction": 0.53,
"RamOverheadFraction": 0.30960337205878574,
"OverheadCostFraction": 0.45485239048108356
},
"totalCost": 0.466114
},
...
"GCP/__undefined__/testuser-opencost/Storage/gke-opencost/Disk/Kubernetes/pvc-95211d76-7842-4182-bdb6-de4133f46b78/pvc-95211d76-7842-4182-bdb6-de4133f46b78": {
"type": "Disk",
"properties": {
"category": "Storage",
"provider": "GCP",
"project": "testuser-opencost",
"service": "Kubernetes",
"cluster": "gke-opencost",
"name": "pvc-95211d76-7842-4182-bdb6-de4133f46b78",
"providerID": "pvc-95211d76-7842-4182-bdb6-de4133f46b78"
},
"labels": {},
"window": {
"start": "2024-06-22T00:00:00Z",
"end": "2024-06-29T00:00:00Z"
},
"start": "2024-06-22T00:00:00Z",
"end": "2024-06-28T06:30:00Z",
"minutes": 9030.000000,
"byteHours": 1292785156096.000000,
"bytes": 8589934592.000000,
"byteHoursUsed": 260162444443.716248,
"byteUsageMax": 2246320128.000000,
"breakdown": {
"idle": 1,
"other": 0,
"system": 0,
"user": 0
},
"adjustment": 0.000000,
"totalCost": 0.065973,
"storageClass": "standard-rwo",
"volumeName": "pvc-95211d76-7842-4182-bdb6-de4133f46b78",
"claimName": "prometheus-server",
"claimNamespace": "prometheus-system"
}
}
}

```

## `/cloudCost` Examples

The OpenCost `/cloudCost` API has query parameters for `window`, `aggregate`, and `filter`. Below are several examples of queries using this API. Please refer to the [OpenCost API](api#cloudcost) for the full API specifics.
Expand Down Expand Up @@ -184,11 +319,11 @@ curl -G http://localhost:9003/cloudCost \
{
"cloudCosts": {
...
"HDEAD-C6F51B-690123/mattray-opencost/GCP/__unallocated__/Management/Kubernetes Engine": {
"HDEAD-B6F51B-690123/testuser-opencost/GCP/__unallocated__/Management/Kubernetes Engine": {
"properties": {
"provider": "GCP",
"accountID": "mattray-opencost",
"invoiceEntityID": "HDEAD-C6F51B-690123",
"accountID": "testuser-opencost",
"invoiceEntityID": "HDEAD-B6F51B-690123",
"service": "Kubernetes Engine",
"category": "Management",
"labels": {
Expand Down Expand Up @@ -223,11 +358,11 @@ curl -G http://localhost:9003/cloudCost \
"kubernetesPercent": 1
}
},
"HDEAD-C6F51B-690123/mattray-opencost/GCP/__unallocated__/Network/Networking": {
"HDEAD-B6F51B-690123/testuser-opencost/GCP/__unallocated__/Network/Networking": {
"properties": {
"provider": "GCP",
"accountID": "mattray-opencost",
"invoiceEntityID": "HDEAD-C6F51B-690123",
"accountID": "testuser-opencost",
"invoiceEntityID": "HDEAD-B6F51B-690123",
"service": "Networking",
"category": "Network"
},
Expand Down Expand Up @@ -257,12 +392,12 @@ curl -G http://localhost:9003/cloudCost \
}
},
...
"HDEAD-C6F51B-690123/mattray-opencost/GCP/gke-opencost-3-default-pool-123456f4-kbl5/Other/Compute Engine": {
"HDEAD-B6F51B-690123/testuser-opencost/GCP/gke-opencost-3-default-pool-123456f4-kbl5/Other/Compute Engine": {
"properties": {
"providerID": "gke-opencost-3-default-pool-123456f4-kbl5",
"provider": "GCP",
"accountID": "mattray-opencost",
"invoiceEntityID": "HDEAD-C6F51B-690123",
"accountID": "testuser-opencost",
"invoiceEntityID": "HDEAD-B6F51B-690123",
"service": "Compute Engine",
"category": "Other",
"labels": {
Expand Down
35 changes: 33 additions & 2 deletions docs/integrations/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ QUERY PARAMETERS
<tr>
<td/>
<td>
Field by which to aggregate the results. Accepts: <code>cluster</code>, <code>node</code>, <code>namespace</code>, <code>controllerKind</code>, <code>controller</code>, <code>service</code>, <code>pod</code>, <code>container</code>, <code>label:LABEL_NAME</code>, and <code>annotation:name</code>. Also accepts comma-separated lists for multi-aggregation, like <code>namespace,label:app</code>.
Field by which to aggregate the results. Accepts: <code>cluster</code>, <code>node</code>, <code>namespace</code>, <code>controllerKind</code>, <code>controller</code>, <code>service</code>, <code>pod</code>, <code>container</code>, <code>label:LABEL_NAME</code>, and <code>annotation:name</code>. Also accepts comma-separated lists for multi-aggregation, like <code>aggregate=namespace,label:app</code>.
<br/><br/>
Examples:<br/>
<ul>
Expand Down Expand Up @@ -112,6 +112,37 @@ QUERY PARAMETERS
</tr>
</table>

## Assets API

The Assets API retrieves backing cost data broken down by individual assets in your cluster. It is not yet exposed in the UI.

### `/assets`
QUERY PARAMETERS
<table>
<tr>
<th id="window">window<a class="hash-link" href="#as_window" title="window">​</a></th>
<th align="left">string</th>
</tr>
<tr>
<td valign="top"><b>required</b></td>
<td>
Duration of time over which to query. Accepts: words like <code>today</code>, <code>week</code>, <code>month</code>, <code>yesterday</code>, <code>lastweek</code>, <code>lastmonth</code>; durations like <code>30m</code>, <code>12h</code>, <code>7d</code>; <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC3339</a> date pairs like <code>2021-01-02T15:04:05Z,2021-02-02T15:04:05Z</code>; <a href="https://www.unixtimestamp.com/">Unix timestamps</a> like <code>1578002645,1580681045</code>.
<br/><br/>
Examples:<br/>
<ul>
<li><code>window=today</code> - The current day</li>
<li><code>window=month</code> - The month-to-date</li>
<li><code>window=lastweek</code> - The previous week</li>
<li><code>window=30m</code> - The last 30 minutes</li>
<li><code>window=12h</code> - The last 12 hours</li>
<li><code>window=7d</code> - The previous 7 days</li>
<li><code>window=2023-01-18T10:30:00Z,2023-01-19T10:30:00Z</code> - <a href="https://datatracker.ietf.org/doc/html/rfc3339">RFC3339</a> date/time range</li>
<li><code>window=1674073869,1674193869</code> - <a href="https://www.unixtimestamp.com/">Unix timestamp</a> range</li>
</ul>
</td>
</tr>
</table>

## Cloud Costs API

The Cloud Costs API retrieves cloud cost data from cloud providers by reading cost and usage reports. You will need additional [configuration](../configuration/) for supporting the billing integration with your cloud provider.
Expand Down Expand Up @@ -151,7 +182,7 @@ QUERY PARAMETERS
<td>
Field by which to aggregate the results.
Accepts: <code>invoiceEntityID</code>, <code>accountID</code>, <code>provider</code>, <code>providerID</code>, <code>category</code>, and <code>service</code>.
Also accepts comma-separated lists for multi-aggregation, like <code>provider,service</code>.
Also accepts comma-separated lists for multi-aggregation, like <code>aggregate=provider,service</code>.
If no value is provided, the entire list of items is returned.
<br/><br/>
Examples:<br/>
Expand Down

0 comments on commit d568014

Please sign in to comment.