Machine identity

Tell the agent which cloud, region, instance type, and pricing a machine has when it cannot detect them

The agent detects what a machine is from the cloud’s metadata service: provider, region, zone, instance type, and whether it is spot or on-demand. Detection works on AWS, Google Cloud, Azure, DigitalOcean, and Hetzner.

Detection is not possible on on-premises servers, private clouds, other providers, or hosts with blocked metadata access. Those machines show up without a region or instance type and cannot be matched to a public price. Set the values yourself to fix that.

Variables

A variable you set wins over what the agent detects. Leave a variable unset to keep the detected value.

Variable	What it sets	Example
COSTGRAPH_PROVIDER	Cloud provider. Lowercased by the agent.	hetzner
COSTGRAPH_REGION	Region.	us-east-1
COSTGRAPH_AVAILABILITY_ZONE	Availability zone.	us-east-1a
COSTGRAPH_INSTANCE_TYPE	Instance type or size.	m6i.large
COSTGRAPH_USAGE_TYPE	on-demand (or ondemand), or spot (or preemptible). Any other value is ignored and logged.	spot
COSTGRAPH_INSTANCE_ID	The provider’s instance id. Also keeps VMs cloned from one image apart. Setting or changing it starts a new machine record.	i-0abc123def4567890
DIGITALOCEAN_TOKEN	Read-only DigitalOcean API token so the agent can read the droplet size.	dop_v1_...
HETZNER_TOKEN	Read-only Hetzner Cloud API token so the agent can read the server type.	...

To get a public price, values must match the price catalog’s naming, for example the AWS region us-east-1 and instance type m6i.large.

Set the variables

Install script

Export the variables before running the install command. The script writes them to the agent’s environment file: /etc/default/costgraph-agent on systemd hosts, /etc/conf.d/costgraph-agent on OpenRC hosts.

export COSTGRAPH_PROVIDER="hetzner"
export COSTGRAPH_REGION="fsn1"
export COSTGRAPH_INSTANCE_TYPE="cx32"
curl -sSL https://setup.costgraph.ai/install.sh | COSTGRAPH_API_KEY="bl_..." sh

Re-running the script keeps any value already recorded in the environment file, so an upgrade does not drop your settings. To change a value, export the new one before running it again. To remove one, delete its line from that file and restart the agent.

Docker

Pass each variable with -e.

docker run -d --name costgraph-agent \
  --restart unless-stopped \
  --pid host \
  --network host \
  -v /proc:/host/proc:ro \
  -v costgraph-agent-state:/var/lib/costgraph-agent \
  -e COSTGRAPH_API_KEY="bl_..." \
  -e COSTGRAPH_PROVIDER="hetzner" \
  -e COSTGRAPH_REGION="fsn1" \
  -e COSTGRAPH_INSTANCE_TYPE="cx32" \
  ghcr.io/baselinehq/costgraph-agent:latest

Ansible

Set the role variables, per host or per group.

Role variable	Sets
costgraph_provider	COSTGRAPH_PROVIDER
costgraph_region	COSTGRAPH_REGION
costgraph_availability_zone	COSTGRAPH_AVAILABILITY_ZONE
costgraph_instance_type	COSTGRAPH_INSTANCE_TYPE
costgraph_usage_type	COSTGRAPH_USAGE_TYPE
costgraph_instance_id	COSTGRAPH_INSTANCE_ID
costgraph_digitalocean_token	DIGITALOCEAN_TOKEN
costgraph_hetzner_token	HETZNER_TOKEN

Helm

Set the identity values for the agent chart.

costgraph:
  agent:
    identity:
      provider: "hetzner"
      region: "fsn1"
      availabilityZone: ""
      instanceType: "cx32"
      usageType: ""
    providerTokensSecret: "provider-tokens"

The values apply to every node the chart runs on, so there is no instance id value. For DigitalOcean or Hetzner tokens, create a Secret with the keys DIGITALOCEAN_TOKEN and HETZNER_TOKEN and name it in providerTokensSecret.

When detection fails at startup

If the agent cannot detect the cloud when it starts, it tries again on its regular metadata interval and updates the machine after detection succeeds. Google Cloud is the exception: restart the agent or set the preceding variables.

On-premises machines

Machines the agent cannot match to a public price can be given one of your organization’s own prices instead. See Pricing IDs.

Machines cloned from one image

Machines cloned from one template share a machine id and can merge into one record in CostGraph. Either regenerate the machine id on each clone, or set COSTGRAPH_INSTANCE_ID to a unique value per machine.

To regenerate the machine id on a systemd host:

sudo rm /etc/machine-id
sudo systemd-machine-id-setup

Also remove /var/lib/dbus/machine-id where it exists. The agent reads that file first and falls back to /etc/machine-id.