Skip to main content

Infracost

Latest release infracost 0.7.4

The Gruntwork-provided Infracost hook estimates the cost of every unit a Pipelines run affects, so a reviewer can see what a change costs before it is applied. It invokes the Infracost CLI directly.

repository {
  after_hook "infracost_estimate" {
    name     = "Infracost Estimate"
    commands = ["plan"]
    execute  = ["pipelines", "hook", "infracost@v0"]
  }
}

The hook should be configured to run after plan given that it estimates the cost of the change that the plan command describes.

Outputs​

The hook posts the estimate on the pull or merge request:

Cost Estimate CommentCost Estimate Comment

The summary line shows the change to your monthly bill. The table breaks that change down by unit, alongside each unit's new monthly cost. The Baseline Cost and Usage Cost columns appear only when usage costs were projected.

A unit whose cost could not be estimated shows ⚠️ in its row, and the summary line reports how many units were not estimated. Its cost contributes zero to the totals.

The hook reports deny when a change exceeds a deny cost threshold. It reports warn when a change exceeds a warn threshold, when a unit could not be estimated, or when the estimate failed. Otherwise it reports pass.

Inputs​

Configure inputs in the hook's env block.

Required

VariableDescription
INFRACOST_API_KEYYour Infracost API key, read by the Infracost CLI. The hook stops before estimating if it is unset.

Optional

VariableDescription
PIPELINES_HOOK_INFRACOST_CLI_VERSIONThe Infracost CLI version the hook installs. Defaults to 0.10.45.
PIPELINES_HOOK_INFRACOST_WARN_TOTAL_COST_ABOVE_AMOUNTA monthly amount. A warning is shown when the new total exceeds it, unless the change lowers your cost.
PIPELINES_HOOK_INFRACOST_WARN_TOTAL_CHANGE_ABOVE_AMOUNTA monthly amount. A warning is shown when the total change exceeds it.
PIPELINES_HOOK_INFRACOST_WARN_TOTAL_CHANGE_ABOVE_PERCENTA percentage increase. A warning is shown when the new total exceeds the previous total by more than this.
PIPELINES_HOOK_INFRACOST_DENY_TOTAL_COST_ABOVE_AMOUNTA monthly amount. The hook blocks merge when the new total exceeds it, unless the change lowers your cost.
PIPELINES_HOOK_INFRACOST_DENY_TOTAL_CHANGE_ABOVE_AMOUNTA monthly amount. The hook blocks merge when the total change exceeds it.
PIPELINES_HOOK_INFRACOST_DENY_TOTAL_CHANGE_ABOVE_PERCENTA percentage increase. The hook blocks merge when the new total exceeds the previous total by more than this.
PIPELINES_HOOK_INFRACOST_LOG_LEVELLog verbosity. A more verbose PIPELINES_LOG_LEVEL overrides it. One of trace, debug, info, warning, error, fatal, panic. Defaults to info.

Infracost CLI settings​

The Infracost CLI reads some of its settings from the environment, and the hook passes them through unchanged. For example, set INFRACOST_CURRENCY to an ISO 4217 currency code to report in a currency other than USD.

repository {
  after_hook "infracost_estimate" {
    name     = "Infracost Estimate"
    commands = ["plan"]
    execute  = ["pipelines", "hook", "infracost@v0"]

    env {
      INFRACOST_CURRENCY = "EUR"
    }
  }
}

The hook also passes an infracost-usage.yml from your repository root to the CLI. See Usage-based costs.

Providing an API key​

Infracost requires an API key, which the hook reads from INFRACOST_API_KEY.

Pipelines does not store secrets for you (see Authentication & Secrets), so fetch the key as part of execute, using the credentials the hook's authentication block provides:

repository {
  after_hook "infracost_estimate" {
    name     = "Infracost Estimate"
    commands = ["plan"]
    execute  = ["bash", "-c", <<-EOT
      export INFRACOST_API_KEY=$(aws ssm get-parameter --name infracost-api-key --with-decryption --query Parameter.Value --output text)
      pipelines hook infracost@v0
    EOT
    ]

    authentication {
      aws_oidc {
        account_id        = "222222222222"
        plan_iam_role_arn = "arn:aws:iam::222222222222:role/infracost-api-key-read"
      }
    }
  }
}

The same approach works with any secret store the hook's identity can reach. For a walkthrough, see Slack Deploy Notification.

Usage-based costs​

Some costs depend on how much a resource is used rather than on it existing, such as requests, storage, and data transfer. Infracost cannot read those figures from a plan, so it projects them.

Commit an infracost-usage.yml at the root of your repository to supply your own projections, and the hook picks it up automatically, with Infracost Cloud usage defaults as a fallback. The footnote under the table names the sources that applied.

See Infracost's usage costs documentation for the file format and how to override individual resources.

Cost thresholds​

Set a threshold to have the hook warn on, or even block, a change that raises your monthly cost above a limit you set. Thresholds apply to the total change for the whole run rather than to individual units, as an amount or as a percentage of the previous total. All are optional.

repository {
  after_hook "infracost_estimate" {
    # ...

    env {
      PIPELINES_HOOK_INFRACOST_WARN_TOTAL_CHANGE_ABOVE_AMOUNT  = "100"
      PIPELINES_HOOK_INFRACOST_DENY_TOTAL_CHANGE_ABOVE_PERCENT = "50"
    }
  }
}

Each threshold is a whole number greater than zero. An amount is in the currency the estimate reports, and a value the hook cannot read fails the run.

A summary of any exceeded cost thresholds appears above the cost estimate table:

Cost Thresholds CommentCost Thresholds Comment

Evaluation​

  • A change equal to a threshold does not exceed it.
  • A change that lowers your monthly cost, or leaves it unchanged, never exceeds a threshold.
  • A percentage threshold is skipped when the previous total is zero, so it never fires on newly created infrastructure. An amount threshold still applies.
  • A unit the hook could not estimate contributes zero, so a change with a ⚠️ row can stay under a threshold its full cost would exceed.
  • A run whose estimate failed reports warn, with no threshold checked.
  • A change that exceeds both a warn and a deny threshold reports deny, and only the deny thresholds are listed.
  • A deny result fails the run and blocks the pull or merge request.