Developers

Terraform

Manage Costfluent objects as code with its Terraform provider, connect cloud accounts in the same apply, and bring objects made in the product under Terraform.

Costfluent publishes a Terraform provider and three cost-access modules on the public Terraform Registry. The registry holds the full reference for each resource and input; this page covers how to set them up, how they fit together, and how objects made in the product come under Terraform.

Before you start

  • Creating the token the provider uses, with the whole Read and write preset, needs the Owner organization role: only an Owner gives an organization token workspace capabilities, and the dialog offers anyone else the preset cut to what they may grant; see API authentication.
  • The provider can do what its token's capabilities allow, and nothing more. It reads the token when it starts, and terraform plan stops before anything is changed when a resource needs a capability the token lacks, naming the capability.

Create a token

  1. Open Settings, then API tokens, and select Create API token.
  2. Enter a Name that says where the token runs, such as the pipeline's name.
  3. Under Start from, choose Read and write. It selects every capability under Capabilities except the Users, teams and channels group, including Manage integrations, Add integrations to workspaces and Remove integrations from workspaces, which costfluent_workspace_provider needs. To manage costfluent_team, costfluent_team_member, costfluent_team_workspace_access or costfluent_app, or to look a member up with costfluent_user, also select the capabilities in that group.
  4. Choose the Expiration and select Create API token.
  5. Copy the token from Your API token. It is shown only once.

Read and write leaves out Users, teams and channels, so a token made from it alone is refused when it reads, creates, changes or deletes a costfluent_team, costfluent_team_member, costfluent_team_workspace_access or costfluent_app, and when it looks a member up with costfluent_user: reading people, teams and channels needs View members. Every other resource works with Read and write, costfluent_workspace_provider included.

Keep the token out of source control: pass it in the COSTFLUENT_API_KEY environment variable, or in a sensitive variable your pipeline fills from its secret store.

Configure the provider

Code
terraform { required_providers { costfluent = { source = "costfluent/costfluent" version = "~> 0.6.0" } } } provider "costfluent" { # Every setting is optional here; the environment variables below fill them instead. # api_key = var.costfluent_api_key # workspace = "wsp_..." # base_url = "https://api.costfluent.com" # timeout = 30 }

Pin the provider to a minor version, as the version line above does. Until version 1.0, a new minor version may need changes to your configuration, and the provider's upgrade guides on the registry list them, for 0.4.0 and for 0.3.0. A patch version never does.

SettingEnvironment variableWhat it does
api_keyCOSTFLUENT_API_KEYThe token. Required in one of the two places.
workspaceCOSTFLUENT_WORKSPACEThe workspace ID, starting with wsp_, that workspace-scoped resources use when they set no workspace_id.
base_urlCOSTFLUENT_BASE_URLThe Public API address. Defaults to https://api.costfluent.com. Must use https; plain http is accepted only for localhost, 127.0.0.1 and ::1.
timeoutnoneHow long one request may take, in seconds. Defaults to 30.

A setting in the provider block wins over its environment variable.

Connect AWS in the same apply

Each cost-access module creates, in your own cloud account, the read-only access Costfluent needs:

The modules do not embed the Costfluent provider, so no Costfluent token enters a cloud pipeline unless you add one. Combined with the provider, one apply creates the access and the connection. For AWS:

Code
terraform { required_providers { aws = { source = "hashicorp/aws" } costfluent = { source = "costfluent/costfluent" version = "~> 0.6.0" } } } provider "aws" { region = "us-east-1" } provider "costfluent" {} # The principal your role must trust, and your organization's external ID. data "costfluent_aws_provider_info" "this" {} module "costfluent_aws" { source = "costfluent/cost-access/aws" version = "~> 0.5" costfluent_principal_arn = data.costfluent_aws_provider_info.this.principal_arn external_id = data.costfluent_aws_provider_info.this.external_id cost_export_bucket_name = "acme-costfluent-export" # omit in a member account } resource "costfluent_provider" "aws" { key = "aws" display_name = "AWS" credentials = module.costfluent_aws.credentials settings = module.costfluent_aws.settings }

The new connection appears under Integrations; choose which workspaces see its cost there (Manage connections). The provider pages cover each cloud in full, with and without Terraform: AWS, Azure, Google Cloud.

Manage objects

ResourceWhat it manages
costfluent_workspaceA workspace, its currency settings, time zone and automatic syncing
costfluent_providerA connection to a cloud account
costfluent_workspace_providerA connection enabled in a workspace, and which of its accounts the workspace reads
costfluent_gcp_service_accountThe Google Cloud service account Costfluent runs for your organization
costfluent_cost_reportA saved cost report
costfluent_business_metricA business metric a report charts cost per unit of; its values are imported by CSV or the API
costfluent_folderA report folder
costfluent_dashboardA dashboard, and the saved filter its report widgets are read through
costfluent_dashboard_widgetA widget on a dashboard: a saved cost report shown as a chart, table or KPI, or text
costfluent_saved_filterA saved filter
costfluent_savings_viewA saved view of a workspace's savings queue: a tab and its filters under a title
costfluent_budgetA budget and its thresholds
costfluent_cost_alertA cost alert
costfluent_segmentA segment
costfluent_allocation_ruleAn allocation rule
costfluent_virtual_tagA virtual tag
costfluent_tag_policyA workspace's tag policy: the required keys its cost must carry
costfluent_cost_report_subscriptionA cost report sent to notification channels on a schedule
costfluent_appA notification channel: email, Slack, Microsoft Teams or a webhook
costfluent_teamA team
costfluent_team_memberA member of the organization in one team, with their role there
costfluent_team_workspace_accessA team's access to one workspace, and the dashboard its members open there

Data sources read workspaces, connections, cost data, cost summaries, anomalies, the findings in a workspace's savings queue (costfluent_savings_items), your plan's entitlements, and what an AWS role must trust (costfluent_aws_provider_info).

Planned: commitment coverage

Not yet available in Costfluent.

costfluent_commitments reads the reservations, savings plans and committed use discounts a workspace's connections hold.

A workspace with a report and a budget:

Code
resource "costfluent_workspace" "production" { name = "Production" currency = "EUR" } resource "costfluent_cost_report" "by_service" { workspace_id = costfluent_workspace.production.id title = "Monthly cost by service" date_interval = "ThisMonth" date_bin = "Day" group_by = [{ dimension = "ServiceName" }] } resource "costfluent_budget" "monthly" { workspace_id = costfluent_workspace.production.id name = "Monthly cloud budget" amount = 10000 currency = "EUR" start_date = "2026-01-01" alerts = [ { threshold_percent = 80 }, { threshold_percent = 100 }, ] }

Bring existing objects under Terraform

An object made in the product, or through the Public API, can be managed by Terraform without recreating it. Write its resource block first, then import it by ID with terraform import or an import block:

TerminalCode
terraform import costfluent_cost_report.by_service wsp_1a2b3c:crp_4d5e6f
Code
import { to = costfluent_budget.monthly id = "bud_7g8h9i" }

The ID's form depends on the resource:

ResourceImport ID
costfluent_workspace, costfluent_provider, costfluent_budget, costfluent_team, costfluent_appThe object's ID
costfluent_cost_report, costfluent_segment, costfluent_allocation_rule, costfluent_workspace_provider<workspace ID>:<object ID>; the workspace is required
costfluent_cost_alert, costfluent_cost_report_subscription, costfluent_dashboard, costfluent_folder, costfluent_saved_filter, costfluent_savings_view, costfluent_virtual_tag, costfluent_business_metric<workspace ID>:<object ID>, or the object's ID alone, which is then read in the provider's workspace
costfluent_dashboard_widget<workspace ID>:<dashboard ID>:<widget ID>, or <dashboard ID>:<widget ID> in the provider's workspace
costfluent_team_member<team ID>:<user ID>
costfluent_team_workspace_access<team ID>:<workspace ID>
costfluent_tag_policyThe workspace's ID: a workspace has one tag policy

costfluent_gcp_service_account cannot be imported, and needs no import: Costfluent creates one service account per organization, and the resource reads it. It provisions on every refresh, so if Costfluent deleted the account because nothing used it (Rotating or removing access), the next plan creates it again and the Costfluent module's grants apply to it in the same apply.

The ID of a workspace, connection, cost report, dashboard or budget is the last part of its page's address in the product: wsp_, prv_, crp_, dsh_ and bud_ start them. The costfluent_workspaces and costfluent_providers data sources list workspaces and connections with their IDs, and the Public API's list endpoints return every other object's ID; see the API reference.

After an import, run terraform plan. A difference it shows is between your configuration and the object as it is; change the configuration until the plan is empty, unless you mean to change the object.

How it behaves

  • A change made in the product to an object Terraform manages shows as drift on the next plan. An object deleted in the product is dropped from the state, and the next plan creates it again.
  • costfluent_provider retries for up to three minutes while new cloud access propagates, such as a role or a dataset grant made earlier in the same apply. Changing a connection's display_name renames it in place: it keeps its ID and the cost it has collected.
  • Destroying a costfluent_provider removes the connection, and erases the cost it imported, as removing it in the product does.
  • Changing a cost report's workspace_id creates the report again in the new workspace.
  • A costfluent_workspace_provider without account_ids, or with an empty set, reads the whole connection, including accounts it discovers later. Changing account_ids or is_enabled updates it in place; changing workspace_id or provider_id creates it again. Creating one or changing its account_ids decides which of the organization's accounts the workspace reads, so it needs an organization token with Manage integrations, and terraform plan refuses a workspace token for it. A workspace token can change is_enabled and destroy the resource. Setting is_enabled = false stops the workspace reading the connection's cost and anomalies and takes the connection off its automatic schedule, while the link and its account_ids stay; true restores both. Destroying it stops that workspace reading the connection; the connection, its cost and other workspaces are unaffected.
  • The API never returns a channel's credentials: a webhook's signing secret and a Slack or Microsoft Teams channel's webhook address read back as ***, and a webhook's url as its scheme and host followed by /***, such as https://hooks.example.com/***. Sending that redacted url back keeps the stored one. costfluent_app keeps the config it applied, so a credential changed in the product does not show as drift, and an imported channel holds the redacted values until the next apply writes the configuration's own. Removing secret from a webhook's config removes its signing: the provider sends the secret as null, because the API keeps the stored secret when an update leaves it out.
  • The Terraform state holds a connection's credentials, a channel's config and a webhook's signing_secret in plaintext. Marking them sensitive only hides them from plan output, so keep the state in an encrypted backend with restricted access.
  • A team's members are costfluent_team_member resources; costfluent_team manages its name only.
  • A costfluent_savings_view keeps a tab of the queue and its filters, as a saved view in the product does. Every change replaces the view whole, so a filter removed from the configuration is cleared. Findings are read-only through Terraform: costfluent_savings_items lists them, and a finding is moved through its states in the product.