Skip to main content

Multi-projects/workspaces

An Infracost config file can be created in each of your Terraform repos to specify how Infracost should be run. The main advantages of this over CLI flags are:

  1. Not having to remember or specify flags for each run. Just run infracost breakdown --config-file infracost.yml instead.
  2. Ability to run Infracost with multiple Terraform projects or workspaces, and combine them into the same breakdown or diff output.
  3. Enable multi-project or workspace runs in CI/CD integrations.
  4. Enable multi-directory Terragrunt projects.

If you're looking to combine cost estimates from multiple runs (e.g. from a CI build matrix), see the infracost output command's docs.

Precedence

Infracost configuration values are chosen in this order:

  1. CLI flags (run infracost --help to see them)
  2. Environment variables
  3. Config file

Usage

  1. Create an infracost.yml file in each of your Terraform project repos. Each project can have the parameters mentioned in the table below; you might find the following examples helpful.

    version: 0.1

    projects:
    - path: path/to/my_terraform
    # other params
    - path: another/project
  2. Pass the file to the infracost breakdown or infracost diff using the --config-file option. This flag should not be confused with the --usage-file option that is used to define resource usage estimates.

ParameterDescriptionNotes
pathPath to the Terraform directory or JSON/plan file. A path can be repeated with different parameters, e.g. for multiple workspaces.Required
usage_filePath to Infracost usage file that specifies values for usage-based resourcesNot required
terraform_binaryUsed to change the path to the terraform or terragrunt binaryNot required, e.g. can be set to ~/bin/terraform_0.13 or another path
terraform_plan_flagsFlags to pass to terraform plan with Terraform directory pathsNot required. Can be space delimited, e.g. -var-file=prod.tfvars -var-file=us-east.tfvars
terraform_workspaceUsed to set the Terraform workspaceNot required. Only set this for multi-workspace deployments, otherwise it might result in the Terraform error "workspaces not supported"
terraform_use_stateUse Terraform state instead of generating a plan, useful if you want to see the breakdown of the current Terraform state.Not required. Applicable when path is a Terraform directory. Can't be used with the diff command.
terraform_cloud_hostFor Terraform Enterprise users, used to override the default app.terraform.io backend hostNot required
terraform_cloud_tokenFor Terraform Cloud/Enterprise users, set this to a Team API Token or User API Token so Infracost can use it to access the planNot required. If this environment variable is set, that'll be used for all projects instead of this parameter
envAny environment variables to pass when running terraform commandsNot required. These should be specified as a map and also supports referencing existing environment variables. This is useful if you want to pass different AWS credentials to different projects (see the Multi-workspaces example below).

Examples

version: 0.1

projects:
- path: examples/terraform
terraform_plan_flags: -var-file=prod.tfvars -var-file=us-east.tfvars
terraform_workspace: prod
env:
AWS_ACCESS_KEY_ID: ${PROD_AWS_ACCESS_KEY_ID}
AWS_SECRET_ACCESS_KEY: ${PROD_AWS_SECRET_ACCESS_KEY}

- path: examples/terraform
terraform_plan_flags: -var-file=stage.tfvars
terraform_workspace: stage
env:
AWS_ACCESS_KEY_ID: ${STAGE_AWS_ACCESS_KEY_ID}
AWS_SECRET_ACCESS_KEY: ${STAGE_AWS_SECRET_ACCESS_KEY}

- path: examples/terraform
terraform_workspace: dev

If your requirements cannot be satisfied with a config file, please create an issue so we can understand the use-case. Also consider using this bash script that demonstrates how to generate plan JSON files for multiple projects and dynamically create a config file that can be used with Infracost.