OpenCost

https://opencost.io/docs
Admin
OpenCost is a vendor-neutral open source project for measuring and allocating cloud infrastructure...
Tokens:74,645
Snippets:631
Trust Score:8.4
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install kubectl-cost with Krew

Source: https://opencost.io/docs/integrations/kubectl-cost

Install the kubectl-cost plugin using the Krew plugin manager. Requires Krew to be installed.

```bash
kubectl krew install cost
```

--------------------------------

### Start OpenCost with Tilt

Source: https://opencost.io/docs/integrations/mcp

Clone the OpenCost repository and start the development environment with Tilt, which automatically starts the MCP server.

```bash
# Clone and start OpenCost with MCP server  

git clone https://github.com/opencost/opencost.git  

cd opencost  

tilt up  

```

--------------------------------

### tilt up CLI example

Source: https://opencost.io/docs/installation/development

Example command for passing Tilt options via the CLI. Options defined here override those from tilt_config.json.

```bash
tilt up -- --arch arm64 --docker-repo dockerhub-username --cloud-integration ../cloud-integration.json --service-key ../service-key.json
```

--------------------------------

### Install Prometheus with Helm

Source: https://opencost.io/docs/configuration/on-prem

Installs Prometheus in the prometheus-system namespace with default settings for use with OpenCost. This is a prerequisite for OpenCost installation.

```bash
helm install prometheus --repo https://prometheus-community.github.io/helm-charts prometheus \

  --namespace prometheus-system --create-namespace \

  --set prometheus-pushgateway.enabled=false \

  --set alertmanager.enabled=false \

  -f https://raw.githubusercontent.com/opencost/opencost/develop/kubernetes/prometheus/extraScrapeConfigs.yaml
```

--------------------------------

### Install OpenCost via Helm Repository

Source: https://opencost.io/docs/configuration/oracle

Adds the OpenCost Helm repository, updates the local repository cache, and installs OpenCost with automatic namespace creation. This is the recommended installation method for OCI environments.

```bash
helm repo add opencost https://opencost.github.io/opencost-helm-chart  

helm repo update  

helm install opencost opencost/opencost --namespace opencost --create-namespace  

```

--------------------------------

### Install OpenCost via Helm Chart

Source: https://opencost.io/docs/configuration/otc

Installs OpenCost using the Helm chart with custom settings from the local.yaml values file. Review values.yaml for available customization settings.

```bash
helm install opencost --repo https://opencost.github.io/opencost-helm-chart opencost \
  --namespace opencost -f local.yaml
```

--------------------------------

### Install OpenCost via Manifest on OCI

Source: https://opencost.io/docs/configuration/otc

Installs OpenCost from the OpenCost manifest on OCI. This is the supported method; standalone Kubernetes manifest installation is no longer supported.

```bash
helm repo add opencost https://opencost.github.io/opencost-helm-chart
helm repo update
helm install opencost opencost/opencost --namespace opencost --create-namespace
```

--------------------------------

### Full example: register and run diagnostics

Source: https://opencost.io/docs/developer/diagnostics-api

Complete example of creating a diagnostic service, registering a diagnostic with a category, running all diagnostics with a 10-second timeout, and processing results. Each diagnostic is limited to a 5-second execution time.

```go
package main  

import (  
    "context"  
    "fmt"  
    "time"  
      
    "github.com/opencost/opencost/core/pkg/diagnostics"  
)  

func main() {  
    const (  
        DiagnosticCategorySystem = "system"  
    )  

    // Create service  
    diagService := diagnostics.NewDiagnosticService()  
      
    // Register diagnostics  
    diagService.Register(  
        "config-check",  
        "Validates system configuration",  
        DiagnosticCategorySystem,  
        func(ctx context.Context) (map[string]any, error) {  
            // run actual diagnostics of configuration checks and report back the  
            // results...   
            return map[string]any{  
                "configValid": true,  
                "lastUpdated": time.Now().Add(-24 * time.Hour),  
            }, nil  
        },  
    )  
      
    // Run ALL diagnostics with 10 second timeout -- Important to note that   
    // each diagnostic is limited to a 5 second execution time  
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)  
    defer cancel()  
      
    results := diagService.Run(ctx)  
      
    // Process results  
    for _, r := range results {  
        if r.Error != "" {  
            fmt.Printf("❌ %s: %s\n", r.Name, r.Error)  
        } else {  
            fmt.Printf("✅ %s: %v\n", r.Name, r.Details)  
        }  
    }  
}  

```

--------------------------------

### Install kubectl-cost manually via curl

Source: https://opencost.io/docs/integrations/kubectl-cost

Manual installation of kubectl-cost using uname, curl, and mv. Downloads the release tarball, extracts it to /tmp, makes it executable, and moves it to /usr/local/bin.

```bash
os=$(uname | tr '[:upper:]' '[:lower:]') && \
arch=$(uname -m | tr '[:upper:]' '[:lower:]' | sed -e s/x86_64/amd64/) && \
curl -s -L https://github.com/kubecost/kubectl-cost/releases/latest/download/kubectl-cost-$os-$arch.tar.gz | tar xz -C /tmp && \
chmod +x /tmp/kubectl-cost && \
sudo mv /tmp/kubectl-cost /usr/local/bin/kubectl-cost
```

--------------------------------

### AWS Provider Configuration Example

Source: https://opencost.io/docs/configuration/aws

Example configuration for the AWS provider, providing default values for instance type and spot information. Includes spot data feed settings and project ID.

```json
{
    "provider": "aws",
    "description": "AWS Provider Configuration. Provides default values used if instance type or spot information is not found.",
    "CPU": "0.031611",
    "spotCPU": "0.006655",
    "RAM": "0.004237",
    "GPU": "0.95",
    "spotRAM": "0.000892",
    "storage": "0.000138888889",
    "zoneNetworkEgress": "0.01",
    "regionNetworkEgress": "0.01",
    "internetNetworkEgress": "0.143",
    "spotLabel": "kops.k8s.io/instancegroup",
    "spotLabelValue": "spotinstance-nodes",
    "awsSpotDataRegion":"us-east-2",
    "awsSpotDataBucket": "my-spot-bucket",
    "awsSpotDataPrefix": "spot_pricing_prefix",
    "projectID": "012345678901"
}
```

--------------------------------

### Create and Start the Export Controller

Source: https://opencost.io/docs/developer/export-api

Creates and starts an ExportController for DiagnosticsRunReport events. It registers a faux diagnostic runner, uses file storage in /tmp, and starts the exporter every 10 seconds. Waits for SIGINT or SIGTERM before exiting.

```go
package main

import (
    "context"
    "math/rand"
    "os"
    "os/signal"
    "syscall"
    "time"

    "github.com/opencost/opencost/core/pkg/diagnostics"
    "github.com/opencost/opencost/core/pkg/storage"
    diagexporter "github.com/opencost/opencost/core/pkg/diagnostics/exporter"
)

const (
    ClusterID = "MyClusterID"
    ApplicationName = "MyApplication"

    ExportFrequency time.Duration = 10 * time.Second
)

// entry point for finops-agent
func main() {
    diag := diagnostics.NewDiagnosticService()

    // register a faux diagnostic runner that will flip a coin
    diag.Register(
        "coin-flip",
        "A randomized diagnostic result",
        "random",
        func(ctx context.Context) (map[string]any, error) {
            result := "tails"
            if rand.Intn(2) == 1 {
                result = "heads"
            }

            return map[string]any{
                "result": result,
            }, nil
        },
    )

    // create a file storage located in the /tmp directory (this will ultimately produce /tmp/<cluster-id>/diagnostics/<application-name>/<time>.json files)
    fileStorage := storage.NewFileStorage("/tmp")

    // diagnostics exporter running every 10 seconds
    diagnosticsExporter := diagexporter.NewDiagnosticsExportController(ClusterID, ApplicationName, fileStorage, diag)
    diagnosticsExporter.Start(ExportFrequency)

    WaitForSignal()
}

// WaitForSignal waits for a termination signal (SIGINT or SIGTERM) and then exits the program.
func WaitForSignal() {
    signalChan := make(chan os.Signal, 1)
    signal.Notify(signalChan, syscall.SIGINT, syscall.SIGTERM)

    done := make(chan struct{}, 1)

    go func() {
        defer close(done)
        <-signalChan
    }()

    <-done
}

```

--------------------------------

### Install Prometheus for OpenCost

Source: https://opencost.io/docs/configuration/otc

Installs Prometheus in the prometheus-system namespace with default settings for use with OpenCost. This command is a prerequisite for OpenCost installation.

```bash
helm install prometheus --repo https://prometheus-community.github.io/helm-charts prometheus \
  --namespace prometheus-system --create-namespace \
  --set prometheus-pushgateway.enabled=false \
  --set alertmanager.enabled=false \
  -f https://raw.githubusercontent.com/opencost/opencost/develop/kubernetes/prometheus/extraScrapeConfigs.yaml
```

--------------------------------

### Example OpenCost values.yaml configuration

Source: https://opencost.io/docs/installation/helm

A comprehensive values.yaml example for OpenCost, configuring Prometheus internal settings, data retention, exporter resources and persistence, custom pricing (AWS), metrics, and UI.

```yaml
opencost:  

  prometheus:  

    internal:  

      namespaceName: monitoring  

      serviceName: prometheus-kube-prometheus-prometheus  

      port: 9090  

  

  dataRetention:  

    dailyResolutionDays: 30  # default: 15  

  

  exporter:  

    defaultClusterId: <cluster name>  

    replicas: 1  

    resources:  

      requests:  

        cpu: "10m"  

        memory: "55Mi"  

      limits:  

        memory: "1Gi"  

    persistence:  

      enabled: true  

      storageClass: "csi-cinder-high-speed"  # adjust based on your environment  

      accessMode: ReadWriteOnce  

      size: 5Gi  

  

  customPricing:  

    enabled: true  

    provider: aws  

    costModel:  

      description: Modified pricing configuration.  

      CPU: 0.031611  

      spotCPU: 0.006655  

      RAM: 0.004237  

      spotRAM: 0.000892  

      GPU: 0.95  

      storage: 0.00005479452  

      zoneNetworkEgress: 0.01  

      regionNetworkEgress: 0.01  

      internetNetworkEgress: 0.143  

      spotLabel: ""  

      spotLabelValue: ""  

      awsServiceKeyName: ""  

      awsServiceKeySecret: ""  

      awsSpotDataRegion: ""  

      awsSpotDataBucket: ""  

      awsSpotDataPrefix: ""  

      athenaBucketName: ""  

      athenaRegion: ""  

      athenaDatabase: ""  

      athenaTable: ""  

      projectID: "${ACCOUNT_ID}"  

  

  metrics:  

    kubeStateMetrics:  

      emitKsmV1Metrics: false  

      emitKsmV1MetricsOnly: false  

    serviceMonitor:  

      enabled: true  

      additionalLabels:  

        release: prometheus  

  

  ui:  

    enabled: true  

```

--------------------------------

### Install OpenCost exporter Helm chart

Source: https://opencost.io/docs/integrations/opencost-exporter

Installs the prometheus-opencost-exporter chart with a specified release name. Replace [RELEASE_NAME] with your desired release name.

```bash
helm install [RELEASE_NAME] prometheus-community/prometheus-opencost-exporter  

```

--------------------------------

### tilt_config.json example

Source: https://opencost.io/docs/installation/development

Example tilt_config.json file for configuring OpenCost with Tilt. The file must be in the root of the OpenCost repository. Omitted values use defaults. Note that port options must be strings in this file.

```json
{
  "arch":"amd64",
  "cloud-integration":"../cloud-integration.json"
}
```

--------------------------------

### ComputeExportControllerGroup usage

Source: https://opencost.io/docs/developer/export-api

Shows how to create compute controllers with different resolutions and group them using ComputeExportControllerGroup, then start them together.

```go
// Create controllers for different resolutions  
hourlyController := NewComputeExportController(source, exporter, time.Hour, time.Minute)  
dailyController := NewComputeExportController(source, exporter, 24*time.Hour, time.Hour)  

// Group them together  
group := NewComputeExportControllerGroup(hourlyController, dailyController)  

// Start all controllers with the same interval  
group.Start(10 * time.Minute)  

```

--------------------------------

### Create OpenCost Namespace

Source: https://opencost.io/docs/configuration/otc

Creates the opencost namespace for the OpenCost installation. Alternate namespaces may be used if necessary.

```bash
kubectl create namespace opencost
```

--------------------------------

### Hourly cost of load balancers by namespace

Source: https://opencost.io/docs/integrations/prometheus

PromQL query to get the hourly cost of all load balancers, broken down by namespace.

```promql
sum(kubecost_load_balancer_cost) by (namespace)  

```

--------------------------------

### GET /model/customCost/total (aggregate=providerId)

Source: https://opencost.io/docs/integrations/api-examples

Example of a GET request to the /model/customCost/total endpoint aggregating by providerId over the past 7 days.

```APIDOC
## GET /model/customCost/total

### Description
Retrieves total custom costs aggregated by providerId over a given time window.

### Method
GET

### Endpoint
/model/customCost/total

### Parameters
#### Query Parameters
- **window** (string) - Required - Time window for the query, e.g., `7d` for the past 7 days.
- **aggregate** (string) - Required - Aggregation dimension, e.g., `providerId`.

### Response
#### Success Response (200)
- **code** (integer) - HTTP status code.
- **data** (object) - Response data containing window, totals, and custom costs.
  - **window** (object) - Start and end timestamps of the query window.
    - **start** (string) - Start timestamp in RFC3339 format.
    - **end** (string) - End timestamp in RFC3339 format.
  - **totalBilledCost** (number) - Total billed cost.
  - **totalListCost** (number) - Total list cost.
  - **customCosts** (array) - List of custom cost entries.
    - **id** (string) - Identifier.
    - **zone** (string) - Zone.
    - **account_name** (string) - Account name.
    - **charge_category** (string) - Charge category.
    - **description** (string) - Description.
    - **resource_name** (string) - Resource name.
    - **resource_type** (string) - Resource type.
    - **provider_id** (string) - Provider identifier.
    - **billedCost** (number) - Billed cost.
    - **listCost** (number) - List cost.
    - **list_unit_price** (number) - List unit price.
    - **usage_quantity** (number) - Usage quantity.
    - **usage_unit** (string) - Usage unit.
    - **domain** (string) - Domain.
    - **cost_source** (string) - Cost source.
    - **aggregate** (string) - Aggregation value.

#### Response Example
```json
{
  "code": 200,
  "data": {
    "window": {
      "start": "2024-03-14T00:00:00Z",
      "end": "2024-03-21T00:00:00Z"
    },
    "totalBilledCost": 147.37999,
    "totalListCost": 186.98546,
    "customCosts": [
      {
        "id": "",
        "zone": "us",
        "account_name": "Kubecost",
        "charge_category": "usage",
        "description": "350+ integrations, alerting, custom metrics & unlimited user accounts",
        "resource_name": "agent_host_count",
        "resource_type": "infra_hosts",
        "provider_id": "42c0ac62-8d80-11ed-96f3-da7ad0900005/agent_host_count",
        "billedCost": 0,
        "listCost": 8.876712,
        "list_unit_price": 0.073972605,
        "usage_quantity": 360,
        "usage_unit": "Infra Host - hours",
        "domain": "datadog",
        "cost_source": "observability",
        "aggregate": "42c0ac62-8d80-11ed-96f3-da7ad0900005/agent_host_count"
      },
      {
        "id": "",
        "zone": "us",
        "account_name": "Kubecost",
        "charge_category": "usage",
        "description": "Centralize your monitoring of systems and services (Per Container)",
        "resource_name": "container_count_excl_agent",
        "resource_type": "infra_hosts",
        "provider_id": "42c0ac62-8d80-11ed-96f3-da7ad0900005/container_count_excl_agent",
        "billedCost": 0,
        "listCost": 19.80274,
        "list_unit_price": 0.0041095894,
        "usage_quantity": 14456,
        "usage_unit": "Container - hours",
        "domain": "datadog",
        "cost_source": "observability",
        "aggregate": "42c0ac62-8d80-11ed-96f3-da7ad0900005/container_count_excl_agent"
      }
    ]
  }
}
```
```

--------------------------------

### GET /model/customCost/total (aggregate=domain)

Source: https://opencost.io/docs/integrations/api-examples

Example of a GET request to the /model/customCost/total endpoint aggregating by domain over the past 7 days.

```APIDOC
## GET /model/customCost/total

### Description
Retrieves total custom costs aggregated by a specified dimension (e.g., domain or providerId) over a given time window.

### Method
GET

### Endpoint
/model/customCost/total

### Parameters
#### Query Parameters
- **window** (string) - Required - Time window for the query, e.g., `7d` for the past 7 days.
- **aggregate** (string) - Required - Aggregation dimension, e.g., `domain` or `providerId`.

### Response
#### Success Response (200)
- **code** (integer) - HTTP status code.
- **data** (object) - Response data containing window, totals, and custom costs.
  - **window** (object) - Start and end timestamps of the query window.
    - **start** (string) - Start timestamp in RFC3339 format.
    - **end** (string) - End timestamp in RFC3339 format.
  - **totalBilledCost** (number) - Total billed cost.
  - **totalListCost** (number) - Total list cost.
  - **customCosts** (array) - List of custom cost entries.
    - **id** (string) - Identifier.
    - **zone** (string) - Zone.
    - **account_name** (string) - Account name.
    - **charge_category** (string) - Charge category.
    - **description** (string) - Description.
    - **resource_name** (string) - Resource name.
    - **resource_type** (string) - Resource type.
    - **provider_id** (string) - Provider identifier.
    - **billedCost** (number) - Billed cost.
    - **listCost** (number) - List cost.
    - **list_unit_price** (number) - List unit price.
    - **usage_quantity** (number) - Usage quantity.
    - **usage_unit** (string) - Usage unit.
    - **domain** (string) - Domain.
    - **cost_source** (string) - Cost source.
    - **aggregate** (string) - Aggregation value.

#### Response Example
```json
{
  "code": 200,
  "data": {
    "window": {
      "start": "2024-03-14T00:00:00Z",
      "end": "2024-03-21T00:00:00Z"
    },
    "totalBilledCost": 147.37999,
    "totalListCost": 186.98547,
    "customCosts": [
      {
        "id": "",
        "zone": "us",
        "account_name": "Kubecost",
        "charge_category": "",
        "description": "",
        "resource_name": "",
        "resource_type": "",
        "provider_id": "",
        "billedCost": 147.37999,
        "listCost": 186.98547,
        "list_unit_price": 0.082197905,
        "usage_quantity": 120,
        "usage_unit": "",
        "domain": "datadog",
        "cost_source": "observability",
        "aggregate": "datadog"
      }
    ]
  }
}
```
```

--------------------------------

### Create a DiagnosticService instance

Source: https://opencost.io/docs/developer/diagnostics-api

Creates a new instance of the diagnostics service.

```go
diagService := diagnostics.NewDiagnosticService()  


```

--------------------------------

### Prometheus externalLabels for Thanos example

Source: https://opencost.io/docs/installation/multi-cluster-single-source-of-data

Example of Prometheus externalLabels configuration used when writing to Thanos. The label key 'cluster' with value 'qa' is used for cluster matching.

```yaml
externalLabels:  

  cluster: qa  

```

--------------------------------

### EventStorageExporter example with JSON output

Source: https://opencost.io/docs/developer/export-api

Complete example of using EventStorageExporter to export a JSON-encoded Message to an in-memory file system. The output shows the file contents at the path federated/cluster-01/message/20250519222700.json.

```go
package main   

import (  

    "time"  

  

    "github.com/opencost/opencost/core/pkg/exporter"  

    "github.com/opencost/opencost/core/pkg/storage"  

    "github.com/opencost/opencost/core/pkg/exporter/pathing"  

)  

  

// constants we'll use in our example for our cluster identifier and event name  

const (  

    ClusterId = "cluster-01"  

    MessageEventName = "message"  

)  

  

// Our 'T' type is a simple struct that contains a message string  

type Message struct {  

    Message string `json:"message"`  

}  

  

func main() {  

    // create the storage.Storage implementation, an in-memory file system   

    store := storage.NewMemoryStorage()  

  

    // create a pathing.StoragePathFormatter implementation specially for exporting "events"   

    pathFormatter, err := pathing.NewEventStoragePathFormatter("federated", ClusterId, MessageEventName)  

    if err != nil {  

        panic("failed to create path formatter: " + err.Error())  

    }  

  

    // create a JSON encoder for our Message type   

    encoder := exporter.NewJSONEncoder[Message]()  

  

    // finally, create the EventStorageExporter implementation for our Message type   

    export := exporter.NewEventStorageExporter(pathFormatter, encoder, store)  

  

    at := time.Now().UTC()   

  

    export.Export(at, &Message{  

        Message: "Testing 1, 2, 3...",  

    })  

}  

```

```json
{  

    "message": "Testing 1, 2, 3..."  

}  

```

--------------------------------

### Create GCP service account and key for OpenCost

Source: https://opencost.io/docs/configuration/gcp

Creates a GCP service account named compute-viewer-opencost with the required roles (compute.viewer, bigquery.user, bigquery.dataViewer, bigquery.jobUser) and generates a service account key file. Run these commands in your GCP project where external costs are run.

```bash
export PROJECT_ID=$(gcloud config get-value project)  

gcloud iam service-accounts create compute-viewer-opencost --display-name "Compute Read Only Account Created For OpenCost" --format json  

gcloud projects add-iam-policy-binding $PROJECT_ID --member serviceAccount:compute-viewer-opencost@$PROJECT_ID.iam.gserviceaccount.com --role roles/compute.viewer  

gcloud projects add-iam-policy-binding $PROJECT_ID --member serviceAccount:compute-viewer-opencost@$PROJECT_ID.iam.gserviceaccount.com --role roles/bigquery.user  

gcloud projects add-iam-policy-binding $PROJECT_ID --member serviceAccount:compute-viewer-opencost@$PROJECT_ID.iam.gserviceaccount.com --role roles/bigquery.dataViewer  

gcloud projects add-iam-policy-binding $PROJECT_ID --member serviceAccount:compute-viewer-opencost@$PROJECT_ID.iam.gserviceaccount.com --role roles/bigquery.jobUser  

gcloud iam service-accounts keys create ./compute-viewer-opencost-key.json --iam-account compute-viewer-opencost@$PROJECT_ID.iam.gserviceaccount.com  

```

--------------------------------

### All billing items for a period of 3 days

Source: https://opencost.io/docs/integrations/api-examples

Returns all billing items for a 3-day period. Warning: may return many megabytes of data depending on cloud provider usage; the example output was heavily pared down from 17 megabytes.

```bash
curl -G http://localhost:9003/cloudCost \
  -d window=2023-10-28T00:00:00Z,2023-10-31T00:00:00Z
```

--------------------------------

### Upgrade OpenCost exporter Helm chart

Source: https://opencost.io/docs/integrations/opencost-exporter

Upgrades the chart to a newer version. Use --install to install if the release does not exist. Replace [RELEASE_NAME] and [CHART] with your release name and chart reference.

```bash
helm upgrade [RELEASE_NAME] [CHART] --install  

```

--------------------------------

### Run diagnostics with Run, RunCategory, and RunDiagnostic

Source: https://opencost.io/docs/developer/diagnostics-api

Shows three ways to run diagnostics: all, by category, or a specific one. Uses a background context.

```go
// Run all diagnostics  

ctx := context.Background()  

allResults := diagService.Run(ctx)  

  

// Run all diagnostics in a specific category  

networkResults := diagService.RunCategory(ctx, "network")  

  

// Run a specific diagnostic  

result := diagService.RunDiagnostic(ctx, "connectivity", "connection-check")  


```

--------------------------------

### Helm values for OpenAI plugin

Source: https://opencost.io/docs/integrations/plugins/openai

Helm values file for installing the OpenAI plugin via the OpenCost Helm chart. Enables the plugin, configures the installation, and sets the OpenAI API key in the configs section.

```yaml
loglevel: debug
plugins:
  enabled: true
  install:
    enabled: true
    fullImageName: curlimages/curl:latest
    folder: /opt/opencost/plugin
    # leave this commented to always download most recent version of plugins
    #version: <INSERT_SPECIFIC_PLUGINS_VERSION>
    # leave this commented to always download most recent version of plugins
    # version: <INSERT_SPECIFIC_PLUGINS_VERSION>
  # the list of enabled plugins
  enabledPlugins:
    - openai
  # pre-existing secret for plugin configuration
  configSecret: ""

configs:
  openai: |
    {
      "openai_api_key": "sk-proj-XXXX"
    }

opencost:
  exporter:
    cloudProviderApiKey: "AIzaSyDXQPG_MHUEy9neR7stolq6l0ujXmjJlvk"
```

--------------------------------

### GET /assets

Source: https://opencost.io/docs/integrations/api-examples

This snippet documents the GET /assets endpoint, which retrieves asset data for a specified time window. It includes the request parameters and a sample response showing asset details such as cost and usage metrics.

```APIDOC
## GET /assets

### Description
Retrieves asset data for a specified time window. The response includes detailed cost and usage information for cloud resources such as nodes and disks.

### Method
GET

### Endpoint
/assets

### Parameters
#### Query Parameters
- **window** (string) - Required - The time window for the asset data, e.g., `7d` for the last 7 days.

### Request Example
```
curl -G http://localhost:9003/assets -d window=7d
```

### Response
#### Success Response (200)
- **code** (integer) - HTTP status code.
- **status** (string) - Status of the response, e.g., "success".
- **data** (object) - Map of asset keys to asset objects. Each asset object contains fields such as `type`, `properties`, `labels`, `window`, `start`, `end`, `minutes`, `totalCost`, and other cost/usage metrics.

#### Response Example
```
{
  "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"
    }
  }
}
```
```

--------------------------------

### Create context with timeout for diagnostics

Source: https://opencost.io/docs/developer/diagnostics-api

Shows how to create a context with a 30-second timeout to prevent diagnostics from running indefinitely. The context is passed to the Run method.

```go
// Create context with timeout  

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)  

defer cancel()  

  

// Run diagnostics with timeout context  

results := diagService.Run(ctx)  

```

--------------------------------

### Pull and run OpenCost UI Docker image

Source: https://opencost.io/docs/installation/docker

Pull and run the OpenCost UI Docker image. Set API_SERVER to host.docker.internal to connect to the OpenCost API running on the host. Access the UI at http://localhost:9090/cloud.

```bash
docker pull ghcr.io/opencost/opencost-ui:1.109.0
```

```bash
docker run -p 9090:9090 -e API_SERVER=host.docker.internal -d ghcr.io/opencost/opencost-ui:1.109.0
```

--------------------------------

### Allocation data for last 60m with step and response

Source: https://opencost.io/docs/integrations/api-examples

Allocation query for the last 60 minutes in 10-minute steps with 1-minute resolution, aggregated by namespace. The response shows a 200 code and a data array with namespace keys.

```bash
curl -G http://localhost:9003/allocation \
  -d window=60m \
  -d step=10m \
  -d resolution=1m \
  -d aggregate=namespace
```

```json
{
  "code": 200,
  "data": [
    {
      "kube-system": { ... },
      "default": { ... },
      "cost-model": { ... }
    }
  ]
}
```

--------------------------------

### GET /customCost/total

Source: https://opencost.io/docs/integrations/api

Retrieves a summary of third-party costs over a specified window.

```APIDOC
## GET /customCost/total

### Description
Used to retrieve a summary of third-party costs over a window.

### Method
GET

### Endpoint
/customCost/total

### Parameters
#### Query Parameters
- **window** (string) - Required - Duration of time over which to query. Accepts: words like `today`, `week`, `month`, `yesterday`, `lastweek`, `lastmonth`; durations like `30m`, `12h`, `7d`; RFC3339 date pairs like `2021-01-02T15:04:05Z,2021-02-02T15:04:05Z`; Unix timestamps like `1578002645,1580681045`.
- **aggregate** (string) - Optional - Field by which to aggregate the results. Accepts: `invoiceEntityID`, `accountID`, `provider`, `providerID`, `category`, and `service`. Also accepts comma-separated lists for multi-aggregation, like `provider,service`. If no value is provided, the entire list of items is returned.
- **accumulate** (string) - Optional - Step size of the accumulation. Accepts: `all`, `hour`, `day`, `week`, `month`, and `quarter`. Default: `day`.
- **filter** (string) - Optional - The available filters are the same as the available aggregations. Accepts: V2 filter parameters.
```

--------------------------------

### GET /cloudCost

Source: https://opencost.io/docs/integrations/api-examples

Documentation for the OpenCost /cloudCost API endpoint, including query parameters and response structure.

```APIDOC
## [GET] /cloudCost

### Description
Retrieves cloud cost data from the OpenCost API. Supports query parameters for `window`, `aggregate`, and `filter` to control the time range and aggregation of the returned cost data.

### Method
GET

### Endpoint
/cloudCost

### Parameters
#### Query Parameters
- **window** (string) - Required - Specifies the time window for the cost data. Can be a relative duration (e.g., `7d`, `14d`) or an explicit start and end time range (e.g., `2023-10-28T00:00:00Z,2023-10-31T00:00:00Z`).
- **aggregate** (string) - Optional - Comma-separated list of aggregation dimensions (e.g., `provider`, `provider,service`).
- **filter** (string) - Optional - Filter criteria for the cost data.

### Request Example
```
curl -G http://localhost:9003/cloudCost \
  -d window=7d \
  -d aggregate=provider
```

### Response
#### Success Response (200)
- **code** (integer) - HTTP status code.
- **data** (object) - Contains the cost data.
  - **sets** (array) - List of cost sets.
    - **cloudCosts** (object) - Map of cloud cost entries keyed by provider/service.
      - **properties** (object) - Properties of the cost entry (e.g., provider, service, category).
      - **window** (object) - Time window for the cost entry.
      - **listCost** (object) - List cost details.
      - **netCost** (object) - Net cost details.
      - **amortizedNetCost** (object) - Amortized net cost details.
      - **invoicedCost** (object) - Invoiced cost details.
      - **amortizedCost** (object) - Amortized cost details.
    - **aggregationProperties** (array) - List of aggregation dimensions used.
  - **window** (object) - Overall time window for the response.

#### Response Example
```
{
  "code": 200,
  "data": {
    "sets": [
      {
        "cloudCosts": {
          "AWS/AWSBackup": { ... },
          "AWS/AWSCloudTrail": {
            "properties": {
              "provider": "AWS",
              "invoiceEntityID": "297945954695",
              "service": "AWSCloudTrail",
              "category": "Other"
            },
            "window": {
              "start": "2023-10-28T00:00:00Z",
              "end": "2023-10-29T00:00:00Z"
            },
            "listCost": {
              "cost": 19.800393,
              "kubernetesPercent": 0
            },
            "netCost": {
              "cost": 19.800393,
              "kubernetesPercent": 0
            },
            "amortizedNetCost": {
              "cost": 19.800393,
              "kubernetesPercent": 0
            },
            "invoicedCost": {
              "cost": 19.800393,
              "kubernetesPercent": 0
            },
            "amortizedCost": {
              "cost": 19.800393,
              "kubernetesPercent": 0
            }
          },
          "AWS/AWSCostExplorer": { ... },
          "AWS/AWSELB": { ... },
          "AWS/AWSGlobalAccelerator": { ... },
          ...
          "GCP/Secret Manager": { ... }
        },
        "aggregationProperties": [
          "provider",
          "service"
        ]
      }
    ],
    "window": {
      "start": "null",
      "end": "null"
    }
  }
}
```
```

--------------------------------

### Run assign-billing-role.bash

Source: https://opencost.io/docs/configuration/azure

Set the required environment variables and run the script to assign the billing role.

```bash
export SP_NAME=OpenCostAccess  

export BILLING_ACCOUNT_ID=<your billing account ID>  

chmod u+x assign-billing-role.bash  

./assign-billing-role.bash  

```

--------------------------------

### Enable Carbon Costs via Helm values.yaml

Source: https://opencost.io/docs/integrations/carbon-costs

Set the Helm flag `carbonEstimates` to `true` in your `values.yaml` to enable carbon costs. Allow approximately ten minutes for pricing information to be derived.

```yaml
kubecostProductConfigs:  

  carbonEstimates:  

    enabled: true  

```

--------------------------------

### Helm chart configuration for OpenCost UI ingress (local.yaml)

Source: https://opencost.io/docs/installation/ui

Add this configuration to the relevant section of your local.yaml and apply via Helm to enable the OpenCost UI and its ingress. Replace HOSTNAME with your desired hostname.

```yaml
opencost:  
  ui:  
    enabled: true  
    ingress:  
      enabled: true  
      hosts:  
        - host: HOSTNAME  
          paths:  
            - /  
```

--------------------------------

### GET /assets

Source: https://opencost.io/docs/integrations/api

Retrieves backing cost data broken down by individual assets in your cluster. Not yet exposed in the UI.

```APIDOC
## GET /assets

### Description
Retrieves backing cost data broken down by individual assets in your cluster. Not yet exposed in the UI.

### Method
GET

### Endpoint
/assets

### Parameters
#### Query Parameters
- **window** (string) - Required - Duration of time over which to query. Accepts: words like `today`, `week`, `month`, `yesterday`, `lastweek`, `lastmonth`; durations like `30m`, `12h`, `7d`; RFC3339 date pairs like `2021-01-02T15:04:05Z,2021-02-02T15:04:05Z`; Unix timestamps like `1578002645,1580681045`. Examples: `window=today`, `window=month`, `window=lastweek`, `window=30m`, `window=12h`, `window=7d`, `window=2023-01-18T10:30:00Z,2023-01-19T10:30:00Z`, `window=1674073869,1674193869`.
```

--------------------------------

### Query cost data with MCP client

Source: https://opencost.io/docs/integrations/mcp

Example of using the MCP client to query cost data for the last 7 days, last 24 hours, and AWS EC2 costs in us-west-1. Demonstrates the get_allocation_costs, get_asset_costs, and get_cloud_costs tools.

```javascript
// Get cost allocation for the last 7 days  

const allocation = await mcpClient.callTool('get_allocation_costs', {  

  window: '7d',  

  aggregate: 'namespace,node'  

});  

  

// Get asset costs for the last 24 hours  

const assets = await mcpClient.callTool('get_asset_costs', {  

  window: '1d'  

});  

  

// Get cloud costs for AWS EC2 in us-west-1  

const cloudCosts = await mcpClient.callTool('get_cloud_costs', {  

  window: '7d',  

  aggregate: 'service',  

  provider: 'aws',  

  service: 'ec2',  

  accumulate: 'day',  

  filter: 'regionID:"us-west-1"'  

});  
```
Tokens:
Raw