Skip to main content

Terraform

Deploy the Infracost Azure integration using the terraform-azure-integration Terraform module (Terraform Registry). Do not use Terraform? See the Azure CLI guide instead. It gives the same result.

note

This integration requires admin access to your Microsoft Entra ID tenant, to the management groups that Infracost reads, and to your billing account. Reach out to support@infracost.io before getting started if you have questions.

Initial Configuration​

Prerequisites​

  • Terraform 1.16 or later.

  • The Azure CLI, signed in to the tenant to set up: az login --tenant <tenant-id>. The Terraform providers use these credentials.

  • The Infracost app client ID — in Infracost Cloud, go to Org Settings > Integrations > Add integrations, click Microsoft Azure, and copy the Infracost app client ID.

  • Your billing account ID:

    • Enterprise Agreement (EA): the enrollment number, for example 12345678.
    • Microsoft Customer Agreement (MCA): the billing account ID, in the format <guid>:<guid>_<yyyy-mm-dd>.

    In the Azure portal, go to Cost Management + Billing > Billing scopes, select the billing account, then Properties.

  • These permissions for the principal that runs Terraform:

StepPermission
Service principalApplication Administrator, Cloud Application Administrator, or Application.ReadWrite.All
Management group rolesOwner or User Access Administrator on each management group
Billing role, EAEnterprise Administrator on the enrollment
Billing role, MCABilling account owner
Billing exportsOwner on the subscription, and billing account access to create the cost export

Step 1: Deploy the Infracost service principal​

The module creates a service principal of the Infracost multi-tenant application in your tenant. Then it assigns the Reader, Cost Management Reader and Monitoring Reader roles to it on your tenant root management group. Infracost uses this service principal to read the data that powers cost visibility features.

Add the providers to your Terraform configuration. The azurerm provider requires a subscription. Use the subscription that will host the billing exports storage account (see Step 3):

terraform {
required_providers {
azuread = {
source = "hashicorp/azuread"
version = "~> 3.0"
}
azurerm = {
source = "hashicorp/azurerm"
version = "~> 4.0"
}
azapi = {
source = "azure/azapi"
version = "~> 2.0"
}
}
}

provider "azuread" {}

provider "azurerm" {
features {}
subscription_id = "YOUR_SUBSCRIPTION_ID"
storage_use_azuread = true
}

provider "azapi" {}

storage_use_azuread = true is required: the billing exports storage account does not allow shared key access.

Then add the module:

module "infracost" {
source = "infracost/integration/azure"
version = "0.6.0"

infracost_client_id = "YOUR_INFRACOST_CLIENT_ID"
billing_agreement_type = "EA" # or "MCA"
billing_account_id = "YOUR_BILLING_ACCOUNT_ID"
billing_exports_location = "westeurope"
}

Replace the values with the values from the prerequisites. Steps 2 and 3 explain the billing variables.

Optional: Limit access to some management groups​

By default, Infracost gets read access on the tenant root management group, which covers all subscriptions in the tenant. To limit access to some management groups, set management_group_names:

module "infracost" {
source = "infracost/integration/azure"
version = "0.6.0"

infracost_client_id = "YOUR_INFRACOST_CLIENT_ID"
management_group_names = ["platform", "workloads"] # <-- Add the management group names

...
}

Optional: Run Terraform as a service principal with limited Graph permissions​

If the principal that runs Terraform only has the Application.ReadWrite.OwnedBy Microsoft Graph permission, it must own the Infracost service principal. Set service_principal_owners to its object ID:

module "infracost" {
...

service_principal_owners = ["OBJECT_ID_OF_THE_TERRAFORM_PRINCIPAL"]
}

Include an outputs.tf so you can easily reference the values needed in a later step:

output "tenant_id" {
description = "The Azure AD tenant ID where the module was provisioned. Provide this to Infracost."
value = module.infracost.tenant_id
}

output "service_principal_object_id" {
description = "Object ID of the Infracost service principal in this tenant."
value = module.infracost.service_principal_object_id
}

output "billing_role_assignment_id" {
description = "ID of the billing role assignment on the billing account."
value = module.infracost.billing_role_assignment_id
}

output "billing_exports" {
description = "Location of the billing exports that Infracost reads. Provide this to Infracost."
value = module.infracost.billing_exports
}

Then run:

terraform init
terraform apply

Once applied, Terraform outputs the tenant ID. You need it in Step 4.

note

When new features are added, this module may need to be updated to include new permissions. Infracost will notify you when an update is required.

Step 2: Enable billing access​

The module assigns a billing reader role to the Infracost service principal on the whole billing account. This gives Infracost read access to all charges, invoices and price sheets of the billing account, beyond the management groups from Step 1:

  • EA: EnrollmentReader on the enrollment.
  • MCA: Billing account reader on the billing account.

Set billing_agreement_type to EA or MCA, and billing_account_id to the value from the prerequisites.

Step 3: Enable the FOCUS 1.2 cost export to Infracost​

A daily cost export is required for Infracost to see individual billing line items. The module can create the export for you, or you can bring your own existing export instead.

Configuration​

By default, the module creates the export. Set billing_exports_location to the Azure region of the storage account:

module "infracost" {
source = "infracost/integration/azure"
version = "0.6.0"

infracost_client_id = "YOUR_INFRACOST_CLIENT_ID"
billing_agreement_type = "EA"
billing_account_id = "YOUR_BILLING_ACCOUNT_ID"
billing_exports_location = "westeurope" # <-- Set the region
}

This provisions, in the subscription of the azurerm provider:

  • the Microsoft.Storage and Microsoft.CostManagement resource provider registrations
  • a resource group, infracost-billing-exports
  • a storage account, named infracost and 15 characters from a hash of the tenant ID
  • a blob container, infracost-exports
  • a daily FOCUS 1.2 cost export of the billing account, InfracostDailyFocusExport, into the focus-cost folder
  • the Storage Blob Data Reader role for Infracost on the container

To change the names, set billing_exports_resource_group_name or billing_exports_storage_account_name.

note

Infracost reads the export periodically, which may incur minor Azure storage transaction costs. Azure storage costs also apply.

The export runs daily from the day after you apply. Azure can take up to 24 hours to write the first export into the container.

Optional: Provide an existing cost export instead​

Use this option if you prefer to manage your own cost export. The module then only gives Infracost read access to the container of your export. When doing so, please contact support@infracost.io to ensure your use case and configuration are supported.

If you create the export manually (for example, in the Azure portal under Cost Management > Exports), configure it with the following settings so Infracost can ingest it:

Manual FOCUS 1.2 settings
SettingValue
ScopeBilling account
Export typeCost and usage (FOCUS 1.2)
Dataset version1.2-preview
FrequencyDaily export of month-to-date costs
FormatParquet
CompressionSnappy
File partitioningOn
Overwrite dataOn
module "infracost" {
source = "infracost/integration/azure"
version = "0.6.0"

infracost_client_id = "YOUR_INFRACOST_CLIENT_ID"
billing_agreement_type = "EA"
billing_account_id = "YOUR_BILLING_ACCOUNT_ID"
provision_billing_exports = false
existing_billing_exports = {
storage_account_id = "/subscriptions/<id>/resourceGroups/<rg>/providers/Microsoft.Storage/storageAccounts/<name>"
container = "<container>"
root_path = "<root-path>"
}
}

Data ownership and lifecycle​

Your Azure subscription retains ownership of the data. Infracost is granted solely read-only access to the export container.

The storage account created by the module has a lifecycle policy: export files move to the cold tier after 90 days, and are deleted after 365 days.

Step 4: Add the integration in the Infracost Cloud​

After deploying the module, add the integration to Infracost from the dashboard:

  1. Go to Org Settings > Integrations > Add integrations, then click Microsoft Azure.
  2. Enter the integration details:
    • Tenant ID: the tenant_id output by the module.
    • Agreement type: Enterprise Agreement (EA) or Microsoft Customer Agreement (MCA).
    • Billing scope ID: the billing account ID that you gave to the module as a path, /providers/Microsoft.Billing/billingAccounts/<billing-account-id>.
    • Alias (optional): a name to identify the integration.
  3. Click Save. Infracost finds the cost export on the billing scope, so you do not enter the storage account.

Upgrading​

As Infracost adds support for additional capabilities there may be a need to upgrade the Terraform module.

Step 1: Update version references​

To upgrade, change the version of the module to the version you'd like to use and make any additional changes needed.

tip

Don't forget to review the release notes for updates and breaking changes.

module "infracost" {
source = "infracost/integration/azure"
- version = "0.5.0"
+ version = "0.6.0"

...
}

Step 2: Download updated module version​

Once you've updated the version, rerun terraform init but add the -upgrade flag to force it to download the correct version of the module:

terraform init -upgrade

Step 3: Plan and Apply​

Now that you've updated the module version, and made any additional modifications, you can run a plan to verify your work, and apply the changes.

terraform plan
terraform apply

Removing​

To remove the Infracost service principal, its role assignments and the billing exports, run terraform destroy against your project.

caution

terraform destroy removes the storage account created by the module, with all exported data. The resource providers stay registered.

Troubleshooting​

Error: billing_account_id is required​

Set billing_agreement_type and billing_account_id.

Error: The azuread and azurerm providers must target the same tenant.​

The azuread and azurerm providers use different tenants. This can happen when you can sign in to more than one tenant, for example as an EA administrator with a different home tenant. Run az login --tenant <tenant-id>, or set tenant_id on both providers.

Error: AuthorizationFailed when creating a role assignment​

The principal that runs Terraform cannot assign roles on the management group or on the storage account. Make sure that it has the Owner or User Access Administrator role on each management group, and the Owner role on the subscription.

Roles that you received a few minutes before the run can still be missing, because Azure takes time to apply them. A role that is eligible in Privileged Identity Management, but not active, is also missing. Activate it and run terraform apply again.