Install

Prerequisites

From CostGraph, one thing: a deployment API key, created in the dashboard under Settings → API Keys. It is the only credential you need. The image registry authenticates with the same key, and the chart wires that up for you. From your side:

Kubernetes and Helm 3+
Postgres 14+, with citext and pg_trgm
Redis
VictoriaMetrics
The URL your users will reach the dashboard on

pg_partman and pg_cron are not strictly required, but install them. Without pg_partman every row lands in one default partition and large tables degrade; without pg_cron partition maintenance is never scheduled, and inserts eventually fail.Managed Postgres (RDS, Cloud SQL) often ships neither. The install still succeeds and warns you.

Sign-in needs no configuration. Your users sign in with their CostGraph accounts; their cost data stays in your network.

Add the Helm repository

helm repo add costgraph https://charts.costgraph.ai
helm repo update

Write a values file

my-values.yaml

controlPlane:
  apiKey: bl_...

appBaseURL: https://costgraph.internal.example.com

postgres:
  url: postgres://[email protected]:5432/costgraph?sslmode=require
  password: ...

redis:
  url: redis://redis.internal:6379

metricsStore:
  url: http://victoria-metrics.internal:8428

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: costgraph.internal.example.com
      paths: [{ path: /, pathType: Prefix }]
  tls:
    - secretName: costgraph-tls
      hosts: [costgraph.internal.example.com]

appBaseURL must be the address people actually open in a browser, not an internal Service DNS name. It shapes the links in invitation email.

Install

helm install costgraph costgraph/costgraph-selfhosted \
  --namespace costgraph --create-namespace \
  -f my-values.yaml

A preflight check runs first and fails the install with the reason if the database cannot support the schema.

Evaluating without a database

To try it before standing up Postgres, Redis and VictoriaMetrics, replace those three blocks with bundled.enabled: true on each and the chart runs them in-cluster:

postgres:
  bundled:
    enabled: true
redis:
  bundled:
    enabled: true
metricsStore:
  bundled:
    enabled: true

Evaluation only. Single replica, no backups, and the bundled Postgres image carries neither pg_partman nor pg_cron, so partition maintenance never runs. A database holding your cost history should outlive a Helm release.

Keeping credentials out of values

For production, put credentials in Secrets you manage and reference them with existingSecret rather than inline values, so nothing sensitive is written into Helm release history:

controlPlane:
  existingSecret: costgraph-control-plane
postgres:
  existingSecret: costgraph-postgres
redis:
  existingSecret: costgraph-redis

When you use controlPlane.existingSecret, create the image pull secret yourself as well and set imagePullSecrets:

kubectl create secret docker-registry costgraph-registry \
  --namespace costgraph \
  --docker-server=registry.costgraph.ai \
  --docker-username=x \
  --docker-password=<your deployment API key>

Network access it needs

Outbound HTTPS (443) to these hosts:

Host	Used for
`api.costgraph.ai`	licensing, cloud price lists, billing quantities, account email
`cognito-idp.us-east-2.amazonaws.com`	verifying sign-in
`registry.costgraph.ai`	pulling the images
`pkg-containers.githubusercontent.com`	the image layers
`us.i.posthog.com`	anonymous product analytics, unless `analytics.enabled: false`

Nothing needs to reach the deployment from outside your network.

Connecting your spend

Installing the chart gives you CostGraph. It does not give it anything to report on yet. That comes from the same sources as hosted CostGraph:

Source	Covers	Set up
Provider integrations	Clouds, databases, AI providers and developer tools you pay for	Integrations
CostGraph Operator	Kubernetes clusters	Operator
CostGraph Agent	Virtual machines and bare metal	Agent
FOCUS push	Anything else, sent to the API yourself	Push FOCUS data

Connect whichever apply to you. Provider integrations need only a read-only credential and nothing deployed.

Pointing them at your install

Everything you deploy defaults to hosted CostGraph, so on a self-hosted install you redirect it at your own address.

Miss this and that cluster or machine reports to hosted CostGraph instead of to you.

For the operator, in every cluster you want costs for, including the one running CostGraph:

helm install costgraph-operator costgraph/costgraph-operator \
  --namespace costgraph --create-namespace \
  --set global.clusterName=<a name for this cluster> \
  --set global.apiKey=<your deployment API key> \
  --set global.backendURL=https://costgraph.internal.example.com/api/v1 \
  --set operatorPrometheus.config.remoteWriteURL=https://costgraph.internal.example.com

Operator setting	Points at	Default if left alone
`global.backendURL`	your install’s API	hosted CostGraph
`operatorPrometheus.config.remoteWriteURL`	your install’s metrics endpoint	`tsdb.costgraph.ai`

The agent and the API take the same treatment: give them your own address in place of api.costgraph.ai, and your deployment API key.

Pricing hardware that is not in a cloud

A resource in a public cloud is priced from that provider’s published rates, matched on its instance type and region. Hardware you own has no published rate, so you register what it costs you and tag the resources that bill at it. This applies whether you measure them with the operator or the agent. Register the rate once, then tag everything that bills at it:

kubectl label node/node-1 \
  costgraph.ai/pricing-id.compute="$COMPUTE_ID" --overwrite

Pricing IDs

Registering rates, the label spellings each platform accepts, and how a rate is inherited from a node to the volumes on it.

Labels are inherited: tagging a node prices the volumes attached to it, so you rarely need to label every object. A node is in no namespace, so labelling a namespace never changes a node’s own rate.

Operating

Resources are named <release>-costgraph-selfhosted. The examples below assume helm install costgraph ...; helm status costgraph prints them with your own release name filled in. Check health at any time. This reads the database and makes no outbound call:

kubectl exec -n costgraph deploy/costgraph-costgraph-selfhosted -- \
  selfhost-doctor -offline

If support asks for a diagnostic bundle. It contains no secrets and no cost data:

kubectl exec -n costgraph deploy/costgraph-costgraph-selfhosted -- \
  selfhost-doctor -bundle -offline

The one thing you must not delete

On first install the chart generates encryption keys into a Secret named <release>-costgraph-selfhosted-generated. Everything you have saved is tied to them. Helm keeps this Secret across upgrades and uninstalls, so normally you need do nothing. But it cannot be regenerated.

If that Secret is deleted, every API key your team issued stops working and every connected cloud account has to be reconnected, because the stored credentials can no longer be decrypted.Back it up alongside the database, and keep the two together. A database restored next to a different Secret is a database whose credentials cannot be read.

kubectl get secret costgraph-costgraph-selfhosted-generated \
  -n costgraph -o yaml > costgraph-keys-backup.yaml

Upgrades

Upgrade in place. Pending migrations are applied on start:

helm upgrade costgraph costgraph/costgraph-selfhosted -f my-values.yaml

Back the database up first. Migrations are not reversible, so rolling the release back does not roll the schema back. A failed upgrade recovers forwards, not by helm rollback.

The chart’s README carries the full recovery procedure for a failed upgrade:

helm show readme costgraph/costgraph-selfhosted

Every setting

values.yaml documents each setting inline, next to the value it controls:

helm show values costgraph/costgraph-selfhosted

Get Started

CostGraph Operator

CostGraph Agent

MCP

Self-Hosted

Integrations

Install

Prerequisites

Install

Evaluating without a database

Keeping credentials out of values

Network access it needs

Connecting your spend

Pointing them at your install

Pricing hardware that is not in a cloud

Pricing IDs

Operating

The one thing you must not delete

Upgrades

Every setting

​Prerequisites

​Install

​Evaluating without a database

​Keeping credentials out of values

​Network access it needs

​Connecting your spend

​Pointing them at your install

​Pricing hardware that is not in a cloud

Pricing IDs

​Operating

​The one thing you must not delete

​Upgrades

​Every setting

Prerequisites

Install

Evaluating without a database

Keeping credentials out of values

Network access it needs

Connecting your spend

Pointing them at your install

Pricing hardware that is not in a cloud

Operating

The one thing you must not delete

Upgrades

Every setting