FinOps as Code

The console is the right place to start, but once you have dozens of teams, hundreds of reports, and allocation logic driving chargeback, changes need review, history, and repeatability. FinOps as Code manages your Vantage configuration the same way you manage infrastructure: in version control, through pull requests, with a plan you review before anything changes. The Vantage Terraform provider and API are the system of record. AI tools like the FinOps Agent, the Vantage MCP, or any coding assistant draft the configuration but never apply it on their own. One rule to remember: AI proposes, Terraform commits, with a human in the loop. This guide shows when FinOps as Code makes sense and several use cases you can adapt. For prompting the FinOps Agent directly, see the companion FinOps AI Prompt Guide.

When to Use FinOps as Code

The console and code are complements, not competitors. The console is built for exploration and answering questions quickly. Code is built for configuration that has to stay correct over time. Most organizations build something in the console first, then promote it to code once it becomes part of a regular process. (This particular pattern is shown in Use Case 5.) Use code when a configuration is:

Shared: Cost Reports, Folders, and Dashboards that multiple teams rely on for recurring reviews.
Durable: Anything that should persist beyond the person who created it and remain intact through team changes.
Sensitive: Allocation logic like Virtual Tags and Billing Rules that reclassifies historical cost and feeds chargeback. These changes deserve a reviewed diff.
Repeated: Work you do the same way every time, like onboarding a new team. Doing it once by hand is fine, but doing it for the fifteenth team is not.
Subject to review or audit: When you need a record of who changed what, when, and why.
Created at scale: Hundreds of teams, accounts, or tag values that are tedious and error-prone to click through.

Stay in the console when work is:

Exploratory: Ad-hoc cost questions, one-off investigations, and “what is driving this?” analysis.
A one-off: A report you need once and will not maintain.
A learning exercise: Trying a feature to understand how it behaves before committing to a pattern.

If you find yourself rebuilding the same console configuration by hand more than twice, that is the signal to move it into code.

Prerequisites

A Vantage account with at least one connected provider.
The Vantage Terraform provider configured with a Read/Write API token. If you do not use Terraform, you can manage the same resources through the corresponding Vantage API endpoints.
A Git repo with a Terraform workflow your team already uses for plan and apply.

Use Cases

Each use case below follows the same shape: a source of truth your organization already maintains, such as a CSV of teams, a YAML org chart, or an export from your identity provider that drives the Vantage configuration. AI drafts the change, you review the plan, and code applies it. This keeps the business logic in one place and scales from five teams to five hundred without changing the workflow.

Onboard a New Team

Create a folder, Cost Report, team, access grant, and budget for every team from one file.

Generate Virtual Tags

Turn a CSV or YAML mapping into a cross-provider allocation tag.

Layered Allocation

Merge several source tags into one canonical chargeback dimension, in priority order.

Durable Reports

Promote a recurring investigation into a committed, version-controlled report.

Import from Console

Bring resources you already built in the console under Terraform management.

Version and Roll Back

Snapshot your allocation config to Git so you can review every change and roll back.

Use Case 1: Onboard a New Team

Every time a new team starts up, you need the same handful of Vantage resources: a folder to organize their reports, a Cost Report filtered to their accounts, a team with an access grant so they can see their data, and a budget to track spend. Keep the team definitions in one file, and let Terraform create every resource from it.

teams.yaml

teams:
  platform:
    workspace_token: wrkspc_abc123
    aws_account_ids: ["123456789012"]
    monthly_budget_usd: 75000
  security:
    workspace_token: wrkspc_abc123
    aws_account_ids: ["234567890123", "345678901234"]
    monthly_budget_usd: 40000

Ask your AI assistant to generate the configuration from that file:

Using our existing Vantage Terraform patterns, generate only the HCL to onboard the teams in teams.yaml. For each team, create a folder, a Cost Report filtered to its AWS accounts, a team, an access grant to its folder, and a monthly budget. Iterate over the file with for_each. Do not create new modules or change existing resources. Return only the diff and your assumptions.

It returns one set of resources per team, driven by for_each:

onboarding.tf

locals {
  teams = yamldecode(file("teams.yaml")).teams
}

resource "vantage_folder" "team" {
  for_each        = local.teams
  title           = "${each.key} Costs"
  workspace_token = each.value.workspace_token
}

resource "vantage_cost_report" "team" {
  for_each     = local.teams
  title        = "${each.key} AWS Costs"
  folder_token = vantage_folder.team[each.key].token
  filter       = "costs.provider = 'aws' AND costs.account_id IN (${join(", ", [for id in each.value.aws_account_ids : "'${id}'"])})"
  groupings    = "service,region"
}

resource "vantage_team" "team" {
  for_each         = local.teams
  name             = each.key
  description      = "Managed by Terraform"
  workspace_tokens = [each.value.workspace_token]
}

resource "vantage_access_grant" "team" {
  for_each       = local.teams
  team_token     = vantage_team.team[each.key].token
  resource_token = vantage_folder.team[each.key].token
  access         = "allowed"
}

resource "vantage_budget" "team" {
  for_each          = local.teams
  name              = "${each.key} Monthly Budget"
  workspace_token   = each.value.workspace_token
  cost_report_token = vantage_cost_report.team[each.key].token
  periods = [
    {
      start_at = "2026-01-01"
      amount   = each.value.monthly_budget_usd
    }
  ]
}

Review the VQL filter before merging. Team onboarding PRs usually succeed or fail based on whether the filter matches the right accounts, tags, and workspace. Creating teams and access grants through Terraform requires Enterprise RBAC and appropriate permissions. For more on teams and access grants, see the RBAC setup guide. To onboard a single new team later, add one entry to teams.yaml and re-run terraform plan. Because every resource is keyed by team name with for_each, Terraform creates only the new team’s resources and leaves the existing teams untouched. The plan shows additions, not a rebuild.

The exact schema for each resource is in the Vantage provider docs on the Terraform Registry. vantage_budget periods take a start_at and amount; end_at is optional. Add one period per month, or generate periods, to cover the full budget window. Validate generated code against the provider docs before applying.

Use Case 2: Generate Virtual Tags from a Source-of-Truth File

Allocation is where code review matters most. A Virtual Tag change can reclassify months of historical cost across every report that groups by that tag. The most maintainable pattern is to keep the mapping that defines the tag, such as teams, accounts, or namespaces, in a file your organization already owns, and generate the tag values from it. The file is the system of record. terraform plan recomputes the tag whenever it changes. Start with the list of teams your organization already maintains:

teams.csv

team
platform
security
data-platform
core-services

This example builds one cross-provider team Virtual Tag that normalizes the AWS team tag and the Kubernetes organization/team label into a single dimension. Terraform reads the CSV and produces one value per team.

team_tag.tf

locals {
  teams = csvdecode(file("teams.csv"))
}

resource "vantage_virtual_tag_config" "team" {
  key            = "team"
  overridable    = true
  backfill_until = "2026-01-01"

  values = [
    for t in local.teams : {
      name   = t.team
      filter = "(costs.provider = 'aws' AND tags.name = 'team' AND tags.value = '${t.team}') OR (costs.provider = 'kubernetes' AND tags.name = 'organization/team' AND tags.value = '${t.team}')"
    }
  ]
}

Or skip writing the HCL and have AI generate it from your file:

Using the Vantage Terraform provider, write a vantage_virtual_tag_config that reads teams.csv (one team per row) and creates a cross-provider "team" Virtual Tag. For each team, generate a value whose VQL matches the AWS tag "team" and the Kubernetes label "organization/team" with that team's name. Return only the HCL.

Before applying, confirm the backfill_until date, verify the tag keys match what your providers actually emit, and keep allocation changes in their own PR. Do not bury them alongside unrelated report updates. Because each value adds processing work, review the Scaling Virtual Tags guide before generating tags with hundreds of values, and see tagging examples for more filter patterns.

Use Case 3: Layered Allocation for Chargeback

Large organizations rarely get a clean allocation dimension from a single source. A team or product name might come from a manually maintained override, a Kubernetes namespace, a provider tag, or a Business Metric, and you need one canonical value with a clear order of precedence. You can build this entirely from Virtual Tags: define a few narrow source tags, then merge them into one standardized key using tag key collapsing, where the first source in the list that has a value wins. First, define the source tags. Each one captures a single way a team value can be derived. Keep them narrow and independent.

team_sources.tf

# Source 1: high-priority manual overrides
resource "vantage_virtual_tag_config" "team_overrides" {
  key         = "team_overrides"
  overridable = true
  values = [
    {
      name   = "platform"
      filter = "costs.provider = 'aws' AND costs.account_id = '123456789012'"
    }
  ]
}

# Source 2: derive team from Kubernetes namespace
resource "vantage_virtual_tag_config" "team_from_namespace" {
  key         = "team_from_namespace"
  overridable = true
  values = [
    {
      name   = "data-platform"
      filter = "costs.provider = 'kubernetes' AND tags.name = 'namespace' AND tags.value IN ('data-ingest', 'data-warehouse')"
    }
  ]
}

Then collapse the sources into one canonical key. The collapsing tag merges the source keys in priority order—list the most authoritative source first, with a raw provider tag at the bottom as a fallback. In this example, the final { key = "team" } entry is the native provider tag key, not another vantage_virtual_tag_config resource.

team.tf

resource "vantage_virtual_tag_config" "team" {
  key            = "team"
  overridable    = true
  backfill_until = "2026-01-01"

  depends_on = [
    vantage_virtual_tag_config.team_overrides,
    vantage_virtual_tag_config.team_from_namespace,
  ]

  collapsed_tag_keys = [
    { key = "team_overrides" },      # manual overrides win
    { key = "team_from_namespace" }, # then namespace-derived values
    { key = "team" }                 # finally, the raw provider tag
  ]
}

The result is a single team dimension you can group and filter by across providers, with deterministic precedence.

Order is precedence: when more than one source has a value for the same cost, the source higher in the list wins. If one of your sources is a cost-based or Business Metric allocation, mind the depth and per-provider rules for allocation chains (up to three allocated tags deep). The Scaling Virtual Tags guide covers precedence, nesting, and processing cost in detail. To manage Business Metrics themselves as code, see Business Metrics in Terraform.

Use Case 4: Turn an Investigation into a Durable Report

Someone from finance asks why data transfer costs jumped last month. You dig into it with the FinOps Agent or a Vantage MCP client and find the answer. Then the thread disappears into chat history and the same question comes back next month. If a question is going to recur, turn the answer into a Terraform-managed Cost Report.

Investigate

Use the FinOps Agent or a Vantage MCP client to identify the services, accounts, regions, and tags driving the cost change.

Draft the report definition

Ask AI to turn the investigation into a VQL filter and grouping strategy, and to explain its assumptions rather than creating anything directly.

Based on this cost investigation, write a Vantage VQL filter and suggested groupings for a Cost Report that tracks these costs going forward. Explain your assumptions and return only the filter and groupings; do not create the report.

Commit the report

data_transfer.tf

resource "vantage_cost_report" "aws_data_transfer" {
  title           = "AWS Data Transfer"
  workspace_token = var.workspace_token
  filter          = "costs.provider = 'aws' AND costs.category = 'Data Transfer'"
  groupings       = "service,account_id,region"
}

Wire it into a review cadence

Add the report to a Dashboard or set up a Report Notification so the stakeholder gets a recurring update without having to ask again.

Use Case 5: Import Console Resources into Terraform

You do not need to start from scratch. Many teams build their initial reporting structure in the console and only move to Terraform once a resource becomes part of a standing process. Examples include a chargeback report that runs monthly, a Virtual Tag that feeds executive Dashboards, or a team structure that needs to stay in sync with your identity provider.

Get the resource token

Copy the token from the console URL (e.g., rprt_1abc23456c7c8a90) or query the API or a Terraform data source.

Define the resource in Terraform

chargeback.tf

resource "vantage_cost_report" "monthly_chargeback" {
  title = "Monthly Chargeback"
}

Import

terraform import vantage_cost_report.monthly_chargeback rprt_1abc23456c7c8a90

Reconcile the plan

Run terraform plan. The first plan will likely show differences between your HCL and the live resource. Update the configuration until the plan is clean. If the diff is confusing, paste it into your AI assistant:

Here is the terraform plan output for a Vantage resource I just imported. Explain which fields are computed defaults I can ignore and which are real differences I need to set in my configuration to make the plan clean.

Not every Vantage resource supports import. Check the Vantage provider docs on the Terraform Registry and the individual resource pages before attempting an import.

Use Case 6: Version and Roll Back Allocation Config

Your allocation logic—the Virtual Tags that drive showback and chargeback—is some of the most valuable configuration in Vantage, and the most tedious to reconstruct by hand if a change does not work out. When it lives in code and Git, every version is saved automatically: you can see exactly what changed between any two points in time and return to a known-good version without rebuilding it from memory. This is the payoff of importing your resources. Once a Virtual Tag is defined in code, Git becomes its version history. You do not have to hand-write the starting configuration. List your Virtual Tag tokens (from the console URL or the vantage_virtual_tag_configs data source), write a Terraform import block for each one, and let Terraform generate the HCL for you.

Terraform import blocks and terraform plan -generate-config-out require Terraform 1.5 or later.

virtual_tags_import.tf

import {
  to = vantage_virtual_tag_config.team
  id = "vtag_1a2b3c4d5e6f7890"
}

import {
  to = vantage_virtual_tag_config.environment
  id = "vtag_0987654321fedcba"
}

Generate the configuration from the live resources, then reconcile until the plan is clean:

terraform plan -generate-config-out=virtual_tags.tf

Terraform writes the current definition of each tag into virtual_tags.tf. Reconcile the generated configuration until the plan is clean, then run terraform apply to complete the import into state. Commit virtual_tags.tf after the import is complete. It is now your baseline version, and the manual work of capturing the existing setup is done once and never again. From here, every change to allocation goes through a pull request, so Git records what changed, when, and why.

Change in a branch

Edit the tag configuration and open a PR. The terraform plan in the PR shows the exact before and after of the allocation change.

Tag a release (optional)

Tag the merge commit (for example, vtags-2026-06-01) so you have named versions to return to.

Roll back when needed

If a change does not pan out, revert to a previous commit and apply it. Vantage restores the Terraform-defined configuration and reprocesses affected allocation tags. There is nothing to rebuild from the audit log or from memory.

git revert <commit>
terraform apply

Keep allocation configuration in its own file and its own PRs (see Guardrails). A clean, isolated history is what makes a confident rollback possible.

Using AI Effectively

AI is what makes FinOps as Code fast: it reads your source files, drafts the HCL, and explains its reasoning so that you spend your time reviewing a diff instead of writing boilerplate. To get accurate output:

Give it the source of truth and the patterns: Point the assistant at your CSV/YAML file and an existing resource in your repo so generated code matches your conventions.
Ask for a diff and assumptions, not actions: Have AI return only the HCL changes and the assumptions it made. Keep it from creating or modifying resources directly.
Make it validate against the provider docs: Ask the assistant to check generated code against the Vantage provider docs on the Terraform Registry. Schemas change (e.g., vantage_budget uses periods, vantage_dashboard uses widgets) and a stale example will not apply cleanly.
Let the plan be the proof: A clean terraform plan is the real test. If the plan is noisy or fails, feed it back to the assistant and ask it to reconcile.

The FinOps Agent is especially useful here because it understands your workspace, RBAC scope, and cost data.

Guardrails

These are worth writing into your team’s operating agreement, not just this guide:

AI never runs terraform apply. A human reviews the plan and merges the PR.
Every PR that touches Vantage resources includes a terraform plan output.
Allocation changes (Virtual Tags, Billing Rules) go in their own PRs, separate from reporting or access changes. These affect historical cost data and should be reviewed with that in mind.
VQL filters get a dedicated review check. A wrong costs.account_id or missing tags.value is the most common source of bad reports.

Frequently Asked Questions

Can I use the console and code at the same time?

Yes. Most teams build and explore in the console, then move the configuration that becomes a standing process into code. The risk is editing a code-managed resource in the console, which causes drift (see below). Decide per resource where the source of truth lives, and keep code-managed resources out of the console for edits.

What happens if someone edits a code-managed resource in the console?

The next terraform plan will show a diff between your HCL and the live resource, and terraform apply will revert the console change to match the code. Treat the plan as a drift detector: if you see unexpected changes, someone edited the resource outside of code. For resources you want to manage in code, make code the only place they are changed.

How should I handle API tokens and Terraform state?

Pass the Vantage API token through an environment variable or your secrets manager, never commit it. Use a remote, shared Terraform backend so your team works from the same state and avoids drift, and keep .terraform/ and local state files out of version control.

Do allocation changes reprocess historical cost data?

Yes. Editing a Virtual Tag or Billing Rule reapplies it across the data in its backfill window, which can reclassify months of cost across every report that uses it. Keep allocation changes in their own PR, set the smallest backfill you actually need, and review the plan with this in mind.

Which resources can I manage as code?

Cost Reports, Folders, Dashboards, Virtual Tags, Cost Allocation Segments, teams, access grants, budgets, Cost Alerts, Billing Rules for eligible MSP accounts, Business Metrics, and more. See the Vantage provider docs on the Terraform Registry for the full list and each resource’s schema, and check there before assuming a resource supports import.

References

Product Documentation
Tutorials and Examples

Overview

Getting Started

FinOps Practice

At Scale

AI & Automation

When to Use FinOps as Code

Prerequisites

Use Cases

Onboard a New Team

Generate Virtual Tags

Layered Allocation

Durable Reports

Import from Console

Version and Roll Back

Use Case 1: Onboard a New Team

Use Case 2: Generate Virtual Tags from a Source-of-Truth File

Use Case 3: Layered Allocation for Chargeback

Use Case 4: Turn an Investigation into a Durable Report

Use Case 5: Import Console Resources into Terraform

Use Case 6: Version and Roll Back Allocation Config

Using AI Effectively

Guardrails

Frequently Asked Questions

References

​When to Use FinOps as Code

​Prerequisites

​Use Cases

Onboard a New Team

Generate Virtual Tags

Layered Allocation

Durable Reports

Import from Console

Version and Roll Back

​Use Case 1: Onboard a New Team

​Use Case 2: Generate Virtual Tags from a Source-of-Truth File

​Use Case 3: Layered Allocation for Chargeback

​Use Case 4: Turn an Investigation into a Durable Report

​Use Case 5: Import Console Resources into Terraform

​Use Case 6: Version and Roll Back Allocation Config

​Using AI Effectively

​Guardrails

​Frequently Asked Questions

​References

When to Use FinOps as Code

Prerequisites

Use Cases

Use Case 1: Onboard a New Team

Use Case 2: Generate Virtual Tags from a Source-of-Truth File

Use Case 3: Layered Allocation for Chargeback

Use Case 4: Turn an Investigation into a Durable Report

Use Case 5: Import Console Resources into Terraform

Use Case 6: Version and Roll Back Allocation Config

Using AI Effectively

Guardrails

Frequently Asked Questions

References