Add API documentation and example for shareIdle and idleByNode parameter

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
+```
+
 ## `/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.

docs/integrations/api.md

@@ -13,7 +13,8 @@ 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 +103,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>
 
 ## Cloud Costs API