Skip to main content

Terraform Provider

Vantage is an official HashiCorp partner and offers a Terraform module for getting up and running with Vantage using Infrastructure as Code (IaC). Vantage also offers a Terraform provider with several resources.

  • Vantage Terraform Integrations module for AWS: The Vantage Terraform Integrations module is available for registered users, across all Vantage tiers, to create the primitives needed to broker a connection with AWS. With the module, you can create a Cross-Account IAM Role as well as a Cost and Usage Report (CUR).
  • Vantage Terraform provider: The Terraform provider comprises several Vantage resources you can create, such as Cost Reports, Dashboards, etc. The Terraform provider makes it possible to fully automate and manage Vantage from within your existing Terraform codebase. Companies with IaC practices can set up, create, and sync their cost reporting structure with Vantage.

Vantage Terraform Integrations Module for AWS

Use the Vantage Integrations module to link your AWS and Vantage accounts. Organizations can leverage the module to integrate thousands of AWS accounts with Vantage. To get set up with this module, see the additional documentation on the Terraform Registry.

note

For root AWS accounts, you will need to provision a CUR bucket using the cur_bucket_name variable. For sub-accounts, you will need to link access, but you won't need to configure the CUR bucket.

The below example shows how to add the management (root) AWS account integration where CUR and an S3 bucket are provisioned:

provider "aws" {
region = "us-east-1"
assume_role {
role_arn = "arn:aws:iam::123456789012:role/admin-role"
}
}

module "vantage-integration" {
source = "vantage-sh/vantage-integration/aws"

# Bucket names must be globally unique. It is provisioned with private acl's
# and only accessed by Vantage via the provisioned cross account role.
cur_bucket_name = "my-company-cur-vantage"
}

The below example shows how to add a member account without a CUR integration. As a result, an IAM Role is created, which Vantage can assume to ingest the cost and resource metadata that are displayed within the Vantage console. See the Terraform documentation for more details.

provider "aws" {
region = "us-east-1"
assume_role {
role_arn = "arn:aws:iam::123456789012:role/admin-:ew
role"
}
}

module "vantage-integration" {
source = "vantage-sh/vantage-integration/aws"
}

Vantage Resources

Using the Terraform provider, you can automate Vantage resources, such as Cost Reports, via the Vantage Write API—or the backbone of the provider.

With the Terraform provider, you can create the following resources:

ResourceTerraform Resource NameDocumentation
Access Grantvantage_access_grantView documentation
Cost Reportvantage_cost_reportView documentation
Dashboardvantage_dashboardView documentation
Foldervantage_folderView documentation
Report Notificationvantage_report_notificationView documentation
Saved Filtervantage_saved_filterView documentation
Segmentvantage_segmentView documentation
Teamvantage_teamView documentation
Important

The ability to create, edit, and destroy resources is keyed to the permissions of the user associated with the API token. For Enterprise customers, role-based access controls also affect these actions. Review the documentation on RBAC for further information.

By using these Terraform resources, engineering teams automate cost reporting in Vantage. Below are some example use cases:

  • Build Cost Reports for hundreds of teams stored in another source of truth (e.g., database or GitHub)
  • Update filters as resource names or tags change
  • Add new reports to team dashboards when new services are deployed
  • Create teams and access grants based on teams within an identity provider (IdP)

Data Sources

The provider also includes the following data sources you can use to pull data from the Vantage console:

  • vantage_access_grants
  • vantage_aws_provider_info
  • vantage_cost_reports
  • vantage_dashboards
  • vantage_folders
  • vantage_saved_filters
  • vantage_segments
  • vantage_teams
  • vantage_users
  • vantage_workspaces

Terraform Examples

Before you begin, ensure you have a valid Write API token.

Create a Cost Report

The following example describes how to create a Cost Report for AWS using Terraform.

  1. First, declare the Vantage provider.

    terraform {
    required_providers {
    vantage = {
    source = "vantage-sh/vantage"
    }
    }
    }

    provider "vantage" {
    api_token = var.api_token
    }
    tip

    You can optionally save your API token as an environment variable and remove the provider "vantage"{...} block. Export your token with: export VANTAGE_API_TOKEN=<YOUR_API_TOKEN>.

  2. Create the vantage_folder resource, with "AWS Costs" as the title.

    resource "vantage_folder" "aws" {
    title = "AWS Costs"
    }
  3. Create the vantage_cost_report resource using the token output from the vantage_folder resource. The Cost Report will be stored in the newly created AWS folder. The Cost Report's title is "AWS Costs." In addition, the vantage_saved_filter resource includes a filter parameter that uses Vantage Query Language (VQL), a SQL-like language for querying cloud cost and usage data. Here, the filter is set to show only AWS costs. Set the groupings parameter to have the report grouped by region and service.

    tip

    Valid groupings include: account_id, billing_account_id, charge_type, cost_category, cost_subcategory, provider, region, resource_id, service, tag:<tag_value>. Enter multiple groupings as comma-separated values: groupings=provider,service,region.

    resource "vantage_cost_report" "aws" {
    folder_token = vantage_folder.aws.token
    filter = "costs.provider = 'aws'"
    title = "AWS Costs"
    groupings = "region,service"
    }

Using Multiple Vantage Terraform Resources

In the following example, we will create a filter, report, and folder to track database costs. This example assumes you've already declared the appropriate providers.

  1. First, create an RDS instance using the aws_db_instance resource from the AWS provider. Then, create a saved filter using the output of the arn from the RDS instance as part of the filter criteria.

    resource "aws_db_instance" "rds" {
    allocated_storage = 10
    db_name = "primary-database"
    engine = "mysql"
    instance_class = "db.t3.micro"
    username = "admin"
    password = "password"
    }

    resource "vantage_saved_filter" "rds" {
    title = "rds-costs"
    filter = "costs.provider='aws' AND costs.resource_id = '${aws_db_instance.rds.arn}' AND costs.service = 'Amazon Relational Database Service'"
    }
  2. Then, create a folder to keep your RDS Cost Reports organized.

    resource "vantage_folder" "rds" {
    title = "RDS Costs"
    }
  3. Finally, use the tokens that are output from the saved filter and folder as input to create a new Cost Report.

    resource "vantage_cost_report" "rds_costs" {
    folder_token = vantage_folder.rds.token
    saved_filter_tokens = [vantage_saved_filter.rds.token]
    title = "RDS Costs"
    }

In this manner, initial setup, deployments, and infrastructure changes are synced to Vantage. Further examples can be found in the terraform-provider-vantage GitHub repository.

Future Primitive Support

Vantage is in the process of expanding the API to support all resources within Vantage. Some future primitives the Terraform provider will support include:

These capabilities will expand the automation capabilities of Vantage through some of the following use cases:

  • Push company metrics to Vantage
  • Sync and update budgets

Feature Requests

To request additional features, please open an issue on GitHub or email us at support@vantage.sh.