Merge branch 'main' into assets

Signed-off-by: Matt Ray <github@mattray.dev>
opencost · Jul 25, 2024 · c9c49c9 · c9c49c9
2 parents d568014 + 7f5fea6
commit c9c49c9
Show file tree

Hide file tree

Showing 5 changed files with 98 additions and 20 deletions.
diff --git a/docs/integrations/api-examples.md b/docs/integrations/api-examples.md
@@ -54,7 +54,7 @@ curl -G http://localhost:9003/allocation \
 curl -G http://localhost:9003/allocation/compute \
   -d window=9d \
   -d step=3d \
-  -d resolution=10m
+  -d resolution=10m \
   -d aggregate=namespace
 ```
 
@@ -81,6 +81,25 @@ curl -G http://localhost:9003/allocation/compute \
 }
 ```
 
+### Allocation data with distributed idle costs
+
+Here's an example of an OpenCost API query that distributes cluster idle costs across all allocations in the cluster:
+
+```sh
+curl -G http://localhost:9003/allocation \
+  -d window=1d \
+  -d shareIdle=true
+```
+
+Here's the same query, but distributing the idle costs of each *node* across all allocations on that node:
+
+```sh
+curl -G http://localhost:9003/allocation \
+  -d window=1d \
+  -d shareIdle=true \
+  -d idleByNode=true
+```
+
 ## `/assets` Example
 
 The OpenCost `/assets` API has the `window` query parameter for retrieving the underlying asset data associated with the Kubernetes cluster.
@@ -214,8 +233,6 @@ curl -G http://localhost:9003/assets -d window=7d
   }
 }
 
-```
-
 ## `/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.

diff --git a/docs/integrations/api.md b/docs/integrations/api.md
@@ -13,7 +13,7 @@ Examples using the API endpoints are provided in the [API Examples](api-examples
 
 ## Allocation API
 
-The standard OpenCost API query for costs and resources allocated to Kubernetes workloads based on on-demand list pricing. You may specify the `window` date range, the Kubernetes primitive(s) to `aggregate` on, the `step` for the duration of returned sets, the `resolution` for the duration to use for Prometheus queries, and `includeIdle` for whether to include the `__idle__` usage for the cluster.
+The standard OpenCost API query for costs and resources allocated to Kubernetes workloads based on on-demand list pricing. You may specify the `window` date range, the Kubernetes primitive(s) to `aggregate` on, the `step` for the duration of returned sets, the `resolution` for the duration to use for Prometheus queries, `includeIdle` for whether to include the `__idle__` usage for the cluster, `shareIdle` for whether to distribute idle costs across non-idle allocations, and `idleByNode` for whether to calculate idle costs per node instead of per cluster.
 
 ### `/allocation`
 QUERY PARAMETERS
@@ -102,14 +102,50 @@ QUERY PARAMETERS
   <tr>
     <td/>
     <td>
-      Whether to return the calculated <code>__idle__</code> field for the query. Default is <code>false</code>.
+      Whether to return the calculated <code>\_\_idle\_\_</code> field for the query. Default is <code>false</code>.
       <br/><br/>
       Examples:<br/>
       <ul>
         <li><code>includeIdle=true</code></li>
       </ul>
     </td>
   </tr>
+  <tr>
+    <th id="shareIdle">shareIdle<a class="hash-link" href="#a_shareidle" title="shareIdle"></a></th>
+    <th align="left">boolean</th>
+  </tr>
+  <tr>
+    <td/>
+    <td>
+      Whether to distribute idle costs across non-idle allocations. Default is <code>false</code>.
+
+      When disabled, idle costs are allocated to a separate <code>\_\_idle\_\_</code> allocation.
+      When enabled, idle costs are distributed across non-idle allocations. This happens proportionally to the non-idle costs of each allocation. For example, if one allocation has twice as much non-idle costs as another, it also receives twice the amount of idle costs. This calculation happens separately for each resource (like CPU or RAM).
+
+      You can choose to distribute idle costs per cluster or per node using the <code>idleByNode</code> parameter.
+
+      <br/><br/>
+      Examples:<br/>
+      <ul>
+        <li><code>shareIdle=true</code></li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <th id="idleByNode">idleByNode<a class="hash-link" href="#a_idlebynode" title="idleByNode"></a></th>
+    <th align="left">boolean</th>
+  </tr>
+  <tr>
+    <td/>
+    <td>
+      Whether to calculate idle costs per node instead of per cluster. Default is <code>false</code>.
+      <br/><br/>
+      Examples:<br/>
+      <ul>
+        <li><code>idleByNode=true</code></li>
+      </ul>
+    </td>
+  </tr>
 </table>
 
 ## Assets API

diff --git a/docs/specification.md b/docs/specification.md
@@ -13,7 +13,7 @@ The OpenCost Spec is a vendor-neutral specification for measuring and allocating
 ## Introduction
 
 
-Kubernetes enables complex deployments of containerized workloads, which are often transient and consume variable amounts of cluster resources. While this enables teams to construct powerful solutions to a broad range of technical problems, it also creates complexities when measuring the resource utilization and costs of workloads and their associated infrastructure within the  dynamics of shared Kubernetes environments.
+Kubernetes enables complex deployments of containerized workloads, which are often transient and consume variable amounts of cluster resources. While this enables teams to construct powerful solutions to a broad range of technical problems, it also creates complexities when measuring the resource utilization and costs of workloads and their associated infrastructure within the dynamics of shared Kubernetes environments.
 
 
 As Kubernetes adoption increases within an organization, these complexities become a business-critical challenge to solve. In this document, we specify a vendor-agnostic methodology for accurately measuring and allocating the costs of a Kubernetes cluster to its hosted tenants. This community resource is maintained by Kubernetes practitioners and we welcome all contributions.
@@ -35,7 +35,7 @@ As Kubernetes adoption increases within an organization, these complexities beco
 </table>
 
 
-Cluster Asset Costs can be further segmented into **Resource Allocation Costs** and **Resource Usage Costs**. Resource Allocation Costs are expenses that accumulate based on the amount of time provisioned irrespective of usage (e.g. CPU hourly rate) whereas Resource Usage Costs accumulate on a per-unit basis (e.g. cost per byte egressed). Costs for an individual Asset are the summation of it’s Resource Allocation and Usage Costs, e.g. a Node’s cost is equal to CPU cost + GPU cost + RAM cost + Node Network Costs
+Cluster Asset Costs can be further segmented into **Resource Allocation Costs** and **Resource Usage Costs**. Resource Allocation Costs are expenses that accumulate based on the amount of time provisioned irrespective of usage (e.g. CPU hourly rate) whereas Resource Usage Costs accumulate on a per-unit basis (e.g. cost per byte egressed). Costs for an individual Asset are the summation of its Resource Allocation and Usage Costs, e.g. a Node’s cost is equal to CPU cost + GPU cost + RAM cost + Node Network Costs
 
 
 <table>

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -25,8 +25,8 @@
     "@mdx-js/react": "^3.0.0",
     "autoprefixer": "^10.4.7",
     "core-js": "^3.27.2",
-    "mobx": "^6.12.4",
-    "postcss": "^8.4.14",
+    "mobx": "^6.13.0",
+    "postcss": "^8.4.39",
     "react-github-btn": "^1.3.0",
     "react-icons": "^5.2.1",
     "styled-components": "^6.1.11",