Terraform provider for Costory

The Costory Terraform provider (costory-io/costory) calls the Costory API from your Terraform configuration. You can create billing datasources, publish enrichments, and manage teams and their members, then review every change in a pull request before terraform apply. The source is on GitHub.

Install the provider

Declare the provider in your configuration, then run terraform init.

terraform {
  required_providers {
    costory = {
      source  = "costory-io/costory"
      version = ">= 0.1.0"
    }
  }
}

The enrichment resources need version 0.3.1 or later.

Authenticate

Create an API token

In the Costory app, open your organization name (top-right) and go to API Tokens. You can create a user-scoped token, or an organization-scoped token if you are an admin. See API overview.

Pass the token to the provider

Declare the token as a sensitive variable and set it in terraform.tfvars or as TF_VAR_costory_api_token.

variable "costory_api_token" {
  type        = string
  description = "Costory API token."
  sensitive   = true
}

provider "costory" {
  token = var.costory_api_token
}

Argument	Required	Description
`token`	Yes	Costory API token. Sensitive.
`base_url`	No	Costory API base URL. Defaults to `https://app-api.costory.io`.

Writing enrichments requires the API token of an organization admin.

Look up the Costory service account

The costory_service_account data source returns the Costory service account name (service_account) and subscription IDs (sub_ids). The AWS and Google Cloud examples use it to grant Costory read access to your billing exports.

data "costory_service_account" "current" {}

output "service_account" {
  value = data.costory_service_account.current.service_account
}

Billing datasources

Each billing datasource is one resource. Costory validates the connection when you apply, so a wrong credential or missing permission fails before any sync starts. terraform destroy deletes the datasource and permanently deletes the data it ingested. See Billing data for history and refresh details. The examples below assume the provider block above. Secrets are passed as sensitive variables.

Resource	Provider	Setup guide
`costory_billing_datasource_aiven`	Aiven	Guide
`costory_billing_datasource_anthropic`	Anthropic Console (API usage)	Guide
`costory_billing_datasource_anthropic_claude_ai`	Anthropic claude.ai	Guide
`costory_billing_datasource_aws`	AWS (CUR 2.0)	Guide
`costory_billing_datasource_azure`	Azure Cost Management	Guide
`costory_billing_datasource_clickhouse_cloud`	ClickHouse Cloud	Guide
`costory_billing_datasource_cloudflare`	Cloudflare	Guide
`costory_billing_datasource_confluent`	Confluent Cloud	Guide
`costory_billing_datasource_cursor`	Cursor	Guide
`costory_billing_datasource_custom_bigquery`	Custom billing table in BigQuery	Guide
`costory_billing_datasource_datadog`	Datadog	Guide
`costory_billing_datasource_elastic_cloud`	Elastic Cloud	Guide
`costory_billing_datasource_gcp`	Google Cloud (BigQuery billing export)	Guide
`costory_billing_datasource_gcp_cud_export`	Google Cloud CUD export	Guide
`costory_billing_datasource_openai`	OpenAI	Guide
`costory_billing_datasource_scaleway`	Scaleway	Guide
`costory_billing_datasource_snowflake`	Snowflake	Guide

Aiven: costory_billing_datasource_aiven

Field details: Aiven setup.

resource "costory_billing_datasource_aiven" "main" {
  name            = "Aiven Billing"
  api_secret      = var.aiven_api_secret
  organization_id = "aiven-organization-id"
}

Anthropic Console (API usage): costory_billing_datasource_anthropic

Field details: Anthropic Console (API usage) setup.

resource "costory_billing_datasource_anthropic" "main" {
  name          = "Anthropic Billing"
  admin_api_key = var.anthropic_admin_api_key
}

Anthropic claude.ai: costory_billing_datasource_anthropic_claude_ai

Field details: Anthropic claude.ai setup.

resource "costory_billing_datasource_anthropic_claude_ai" "main" {
  name              = "Anthropic Claude AI Billing"
  analytics_api_key = var.anthropic_claude_ai_analytics_api_key
  account_name      = "acme"
}

AWS (CUR 2.0): costory_billing_datasource_aws

The bucket, IAM role and CUR 2.0 export come from the full configuration in AWS billing setup. The resource below is the Costory part.

resource "costory_billing_datasource_aws" "main" {
  name                   = "AWS CUR ${var.s3_name}"
  bucket_name            = aws_s3_bucket.s3_client_bucket.bucket
  role_arn               = aws_iam_role.costory_federated_role.arn
  prefix                 = var.s3_prefix
  eks_split_data_enabled = true
  depends_on             = [aws_bcmdataexports_export.cur_report_definition]
}

Azure Cost Management: costory_billing_datasource_azure

The storage account, container, SAS URL and exports come from the full configuration in Azure billing setup. The resource below is the Costory part.

resource "costory_billing_datasource_azure" "main" {
  name                 = "Azure Production"
  sas_url              = local.blob_endpoint_with_sas
  storage_account_name = azurerm_storage_account.cost_exports.name
  container_name       = azurerm_storage_container.billing.name
  actuals_path         = "actuals/${local.actuals_export_name}"
  amortized_path       = "amortized/${local.amortized_export_name}"
}

ClickHouse Cloud: costory_billing_datasource_clickhouse_cloud

Field details: ClickHouse Cloud setup.

resource "costory_billing_datasource_clickhouse_cloud" "main" {
  name            = "ClickHouse Cloud Billing"
  key_id          = "key-id"
  key_secret      = var.clickhouse_cloud_key_secret
  organization_id = "org-123"
}

Cloudflare: costory_billing_datasource_cloudflare

Field details: Cloudflare setup.

resource "costory_billing_datasource_cloudflare" "main" {
  name       = "Cloudflare Billing"
  api_token  = var.cloudflare_api_token
  account_id = "cloudflare-account-id"
}

Confluent Cloud: costory_billing_datasource_confluent

Field details: Confluent Cloud setup.

resource "costory_billing_datasource_confluent" "main" {
  name       = "Confluent Billing"
  api_key    = var.confluent_api_key
  api_secret = var.confluent_api_secret
}

Cursor: costory_billing_datasource_cursor

Field details: Cursor setup.

resource "costory_billing_datasource_cursor" "main" {
  name          = "Cursor Billing"
  admin_api_key = var.cursor_admin_api_key
}

Custom billing table in BigQuery: costory_billing_datasource_custom_bigquery

Maps the columns of your own BigQuery cost table to Costory billing fields. billed_cost is required. Full schema: Registry.

resource "costory_billing_datasource_custom_bigquery" "main" {
  name          = "Custom BigQuery Billing"
  bq_table_path = "my-project.custom.costs"
  provider_name = "acme"

  mapping = {
    billed_cost  = "cost"
    service_name = "sku"
  }
}

Datadog: costory_billing_datasource_datadog

Field details: Datadog setup.

resource "costory_billing_datasource_datadog" "main" {
  name            = "Datadog Billing"
  api_key         = var.datadog_api_key
  application_key = var.datadog_application_key
  region          = "datadoghq.com"
}

Elastic Cloud: costory_billing_datasource_elastic_cloud

Field details: Elastic Cloud setup.

resource "costory_billing_datasource_elastic_cloud" "main" {
  name            = "Elastic Cloud Billing"
  api_key         = var.elastic_cloud_api_key
  organization_id = var.elastic_cloud_organization_id
}

Google Cloud (BigQuery billing export): costory_billing_datasource_gcp

The example grants the Costory service account read access to your billing export dataset, then creates the datasource. Full walkthrough: Google Cloud billing setup.

locals {
  bigquery_roles = toset([
    "roles/bigquery.metadataViewer",
    "roles/bigquery.dataViewer",
  ])
  # Set the BigQuery project, dataset, and table IDs where your detailed billing data is exported.
  bigquery_project_id = "my-project"
  bigquery_dataset_id = "billing_export"
  bigquery_table_id   = "gcp_billing_export_v1_0123"
}

resource "google_bigquery_dataset_iam_member" "costory_access" {
  for_each   = local.bigquery_roles
  project    = local.bigquery_project_id
  dataset_id = local.bigquery_dataset_id
  role       = each.key
  member     = "serviceAccount:${data.costory_service_account.current.service_account}"
}

resource "costory_billing_datasource_gcp" "main" {
  name                = "GCP Billing Export"
  bq_uri              = "${local.bigquery_project_id}.${local.bigquery_dataset_id}.${local.bigquery_table_id}"
  is_detailed_billing = true
  depends_on          = [google_bigquery_dataset_iam_member.costory_access]
}

Google Cloud CUD export: costory_billing_datasource_gcp_cud_export

Field details: Google Cloud CUD export setup.

resource "costory_billing_datasource_gcp_cud_export" "main" {
  name          = "GCP CUD Export"
  bq_table_path = "my-project.billing.cud_export"
}

OpenAI: costory_billing_datasource_openai

Field details: OpenAI setup.

resource "costory_billing_datasource_openai" "main" {
  name          = "OpenAI Billing"
  admin_api_key = var.openai_admin_api_key
}

Scaleway: costory_billing_datasource_scaleway

Field details: Scaleway setup.

resource "costory_billing_datasource_scaleway" "main" {
  name            = "Scaleway Billing"
  secret_key      = var.scaleway_secret_key
  organization_id = "scaleway-organization-id"
}

Snowflake: costory_billing_datasource_snowflake

Field details: Snowflake setup.

resource "costory_billing_datasource_snowflake" "main" {
  name           = "Snowflake Billing"
  integration_id = "snowflake-integration-id"
}

Enrichments

costory_enrichment stores one YAML lookup file as a draft. costory_enrichments_publish publishes every draft in one transaction after the files are written, and removes the enrichments whose file you deleted. See Publish with Terraform for the file format.

# One resource per YAML file in ./enrichments. Applying stores drafts;
# costory_enrichments_publish makes them live.
resource "costory_enrichment" "all" {
  for_each = fileset("${path.module}/enrichments", "*.yaml")

  name = trimsuffix(each.value, ".yaml")
  file = "${path.module}/enrichments/${each.value}"
}

# Publishes every draft in one transaction after the enrichments are written,
# and removes the enrichments whose file was deleted.
resource "costory_enrichments_publish" "this" {
  enrichments = { for enrichment in costory_enrichment.all : enrichment.name => enrichment.content_sha256 }
}

Teams and members

costory_team creates a PUBLIC or PRIVATE team. costory_team_member adds a member by email or user_id, with the OWNER or MEMBER role. Team scopes are still managed in the UI. See Teams.

resource "costory_team" "engineering" {
  name        = "Engineering"
  description = "All engineering members"
  visibility  = "PUBLIC"
}

variable "team_members" {
  type = map(object({
    email = string
    role  = string
  }))
  default = {
    alice = { email = "alice@example.com", role = "OWNER" }
    bob   = { email = "bob@example.com", role = "MEMBER" }
    carol = { email = "carol@example.com", role = "MEMBER" }
  }
}

resource "costory_team_member" "members" {
  for_each = var.team_members

  team_id = costory_team.engineering.id
  email   = each.value.email
  role    = each.value.role
}

Billing data

Every provider, history and refresh

Enrichments

YAML lookup files you keep in git

Teams

Team creation, members and scopes

Terraform Registry

Full schema for every resource

Get Started

Setup

Understand

Tag & Allocate

Share

Teams

Technical Documentation

Glossary

Resources

Install the provider

Authenticate

Look up the Costory service account

Billing datasources

Enrichments

Teams and members

Billing data

Enrichments

Teams

Terraform Registry

​Install the provider

​Authenticate

​Look up the Costory service account

​Billing datasources

​Enrichments

​Teams and members

​Related

Billing data

Enrichments

Teams

Terraform Registry

Install the provider

Authenticate

Look up the Costory service account

Billing datasources

Enrichments

Teams and members

Related