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 planstops before anything is changed when a resource needs a capability the token lacks, naming the capability.
Create a token
- Open Settings, then API tokens, and select Create API token.
- Enter a Name that says where the token runs, such as the pipeline's name.
- 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_providerneeds. To managecostfluent_team,costfluent_team_member,costfluent_team_workspace_accessorcostfluent_app, or to look a member up withcostfluent_user, also select the capabilities in that group. - Choose the Expiration and select Create API token.
- 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
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.
| Setting | Environment variable | What it does |
|---|---|---|
api_key | COSTFLUENT_API_KEY | The token. Required in one of the two places. |
workspace | COSTFLUENT_WORKSPACE | The workspace ID, starting with wsp_, that workspace-scoped resources use when they set no workspace_id. |
base_url | COSTFLUENT_BASE_URL | The 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. |
timeout | none | How 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:
costfluent/cost-access/aws: the IAM role Costfluent assumes and, in a management account, the cost export it reads.costfluent/cost-access/azure: a service principal with read access to cost data.costfluent/cost-access/gcp: read access to one billing export.
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
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
| Resource | What it manages |
|---|---|
costfluent_workspace | A workspace, its currency settings, time zone and automatic syncing |
costfluent_provider | A connection to a cloud account |
costfluent_workspace_provider | A connection enabled in a workspace, and which of its accounts the workspace reads |
costfluent_gcp_service_account | The Google Cloud service account Costfluent runs for your organization |
costfluent_cost_report | A saved cost report |
costfluent_business_metric | A business metric a report charts cost per unit of; its values are imported by CSV or the API |
costfluent_folder | A report folder |
costfluent_dashboard | A dashboard, and the saved filter its report widgets are read through |
costfluent_dashboard_widget | A widget on a dashboard: a saved cost report shown as a chart, table or KPI, or text |
costfluent_saved_filter | A saved filter |
costfluent_savings_view | A saved view of a workspace's savings queue: a tab and its filters under a title |
costfluent_budget | A budget and its thresholds |
costfluent_cost_alert | A cost alert |
costfluent_segment | A segment |
costfluent_allocation_rule | An allocation rule |
costfluent_virtual_tag | A virtual tag |
costfluent_tag_policy | A workspace's tag policy: the required keys its cost must carry |
costfluent_cost_report_subscription | A cost report sent to notification channels on a schedule |
costfluent_app | A notification channel: email, Slack, Microsoft Teams or a webhook |
costfluent_team | A team |
costfluent_team_member | A member of the organization in one team, with their role there |
costfluent_team_workspace_access | A 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
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
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:
Code
Code
The ID's form depends on the resource:
| Resource | Import ID |
|---|---|
costfluent_workspace, costfluent_provider, costfluent_budget, costfluent_team, costfluent_app | The 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_policy | The 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_providerretries 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'sdisplay_namerenames it in place: it keeps its ID and the cost it has collected.- Destroying a
costfluent_providerremoves the connection, and erases the cost it imported, as removing it in the product does. - Changing a cost report's
workspace_idcreates the report again in the new workspace. - A
costfluent_workspace_providerwithoutaccount_ids, or with an empty set, reads the whole connection, including accounts it discovers later. Changingaccount_idsoris_enabledupdates it in place; changingworkspace_idorprovider_idcreates it again. Creating one or changing itsaccount_idsdecides which of the organization's accounts the workspace reads, so it needs an organization token with Manage integrations, andterraform planrefuses a workspace token for it. A workspace token can changeis_enabledand destroy the resource. Settingis_enabled = falsestops the workspace reading the connection's cost and anomalies and takes the connection off its automatic schedule, while the link and itsaccount_idsstay;truerestores 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'surlas its scheme and host followed by/***, such ashttps://hooks.example.com/***. Sending that redactedurlback keeps the stored one.costfluent_appkeeps theconfigit 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. Removingsecretfrom a webhook'sconfigremoves its signing: the provider sends the secret asnull, because the API keeps the stored secret when an update leaves it out. - The Terraform state holds a connection's
credentials, a channel'sconfigand a webhook'ssigning_secretin 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_memberresources;costfluent_teammanages its name only. - A
costfluent_savings_viewkeeps 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_itemslists them, and a finding is moved through its states in the product.