Getting started

Infracost shows cloud cost estimates for infrastructure-as-code projects such as Terraform. It helps developers, devops and others to quickly see a cost breakdown and compare different options upfront.

If you're upgrading from an older version to v0.8, please see the migration guide.

Installation

1. Install Infracost

Assuming Terraform is already installed, get the latest Infracost release:

macOS Homebrew

brew install infracost

Subsequent updates can be installed in the usual way: brew upgrade infracost (you might need brew update first if your brew isn't up-to-date)

macOS manual

arch=$(uname -m | tr '[:upper:]' '[:lower:]' | sed -e s/x86_64/amd64/) && \

curl -s -L https://github.com/infracost/infracost/releases/latest/download/infracost-darwin-$arch.tar.gz | tar xz -C /tmp && \

sudo mv /tmp/infracost-darwin-${arch} /usr/local/bin/infracost

Linux

curl -s -L https://github.com/infracost/infracost/releases/latest/download/infracost-linux-amd64.tar.gz | tar xz -C /tmp && \

sudo mv /tmp/infracost-linux-amd64 /usr/local/bin/infracost

Docker

docker pull infracost/infracost

docker run --rm \

-e INFRACOST_API_KEY=see_following_step_on_how_to_get_this \

-e AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID \

-e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY \

-v $PWD/:/code/ infracost/infracost breakdown --path /code/

# Add other required flags/envs for Infracost or Terraform

# For example, these might be required if you are using AWS assume-role:

# -e AWS_SESSION_TOKEN=$AWS_SESSION_TOKEN \

# -e AWS_REGION=$AWS_REGION \

Windows

Download and unzip the latest release. Rename the file infracost-windows-amd64 to infracost.exe, then run it from the Command Prompt or Powershell using .\infracost.exe --no-color alongside other required commands/flags (color output has a bug we need to fix on Windows). You should also move the exe file to a folder that is in your PATH environment variable, e.g. C:\Windows.

2. Get API key

Register for a free API key:

infracost register

The key is saved in ~/.config/infracost/credentials.yml.

3. Run it

Run Infracost using our example Terraform project to see how it works:

git clone https://github.com/infracost/example-terraform.git

cd example-terraform

# Play with sample1/main.tf and re-run to compare costs

infracost breakdown --path sample1

# Show diff of monthly costs, edit the yaml file and re-run to compare costs

infracost diff --path sample1 --usage-file sample1/infracost-usage.yml

Use our CI/CD integrations to automatically add pull request comments showing cost estimate diffs.

Usage

As mentioned in the FAQ, no cloud credentials, secrets, tags or resource identifiers are sent to the Cloud Pricing API. That API does not become aware of your cloud spend; it simply returns cloud prices to the CLI so calculations can be done on your machine. Infracost does not make any changes to your Terraform state or cloud resources.

The infracost CLI has the following main commands. Use the --path flag to point to a Terraform directory or plan JSON file:

• breakdown: show full breakdown of costs
• diff: show diff of monthly costs between current and planned state

If your repo has multiple Terraform projects or workspaces, use an Infracost config file to define them; their results will be combined into the same breakdown or diff output.

Terraform directory

As shown below, any required Terraform flags can be passed using --terraform-plan-flags. The --terraform-workspace flag can be used to define a workspace.

Internally Infracost runs Terraform init, plan and show; init requires cloud credentials to be set, e.g. via the usual AWS_ACCESS_KEY_ID or GOOGLE_CREDENTIALS environment variables.

infracost breakdown --path /code --terraform-plan-flags "-var-file=my.tfvars"

infracost diff --path /code --terraform-plan-flags "-var-file=my.tfvars"

Terraform plan JSON

Point to a Terraform plan JSON file using --path. This implies that Terraform init has been run, thus Infracost just runs Terraform show, which does not require cloud creds to be set.

cd path/to/code

terraform init

terraform plan -out tfplan.binary

terraform show -json tfplan.binary > plan.json

infracost breakdown --path plan.json

infracost diff --path plan.json

See the advanced usage guide for other usage options.

Useful options

Run infracost breakdown --help to see the available options, which include:

--terraform-workspace Terraform workspace to use. Applicable when path is a Terraform directory

--format Output format: json, table, html (default "table")

--config-file Path to Infracost config file. Cannot be used with path, terraform* or usage-file flags

--usage-file Path to Infracost usage file that specifies values for usage-based resources

--sync-usage-file Sync usage-file with missing resources, needs usage-file too (experimental)

--show-skipped Show unsupported resources, some of which might be free

--log-level Use "debug" to troubleshoot, can be set to "info" or "warn" in CI/CD systems to reduce noise, turns off spinners in output

--no-color Turn off colored output

The infracost diff --help and infracost output --help commands show related options.