Skip to main content

Guardrails

Guardrails help you control costs by monitoring pull requests (PRs) and triggering actions when your defined thresholds are exceeded. Once you define a cost or percentage-based threshold for the relevant repositories, projects, and branches, you can set up email, Slack, or Microsoft Teams notifications. You can also customize the PR comment (e.g. "This change exceeds the budget, please discuss with your team lead") or even block the PR until it has been reviewed.

Cost savings from guardrails

Guardrails also have an audit trail of the pull requests that triggered them:

Guardrail events

Usage​

You can create multiple guardrails, for example one with a lower threshold that simply notifies team leads and FinOps, and another one with a very high threshold that blocks the pull request until it has been reviewed.

To create a guardrail, log in to Infracost Cloud and go to the Guardrails page.

1. Scope of the guardrail​

Give your guardrail a name, and select the whether the guardrail should be evaluated against the pull request cost as a whole, or against projects individually.

Projects are an optional sub-grouping concept within a repo and can be mapped to things like workspaces (e.g., dev/stage/prod) or Terraform modules (e.g., auth/api/dashboard).

Guardrail name and scope

2. Pull requests to monitor and thresholds​

Next you should select any filters for the pull requests that this guardrail will monitor, e.g. only monitor pull requests in certain repositories.

Then you should select the thresholds that should trigger this guardrail, the three common use-cases are:

  1. Total monthly cost exceeds the budget: triggered when a pull request's monthly cost exceeds this value, which protects against monthly budgets being exceeded.
  2. Increases monthly cost by a fixed amount: triggered when a pull request's monthly cost increases by more than this value, which protects against unexpected cost spikes.
  3. Increases monthly cost by percentage: triggered when a pull request's monthly cost increases by more than this percent, which also protects against unexpected cost spikes.
Create a guardrail using pull request filters, and the thresholds that should trigger the guardrail

3. Notifications to send​

You can select the users who should be emailed when a guardrail is triggered. You can also create a Slack channel webhook and use that for notifications.

We recommend enabling the pull request option, so engineers are shown the guardrail information in the Infracost pull request comment too. The pull request option only works if you are using the GitHub App integration or the infracost comment command in CI/CD.

Regardless of which notification option you select, you can set a custom message to be included in them to give additional context or instructions. For example, you can describe why this guardrail is important or what will happen next after someone has reviewed the notification.

Select the notifications that should be sent when the guardrail is triggered

Email​

The following screenshot shows an example email notification.

Example email notification

Slack​

The following screenshot shows an example Slack notification.

Example Slack message

Microsoft Teams​

Guardrails can send an email to Microsoft Teams channel email addresses, which will be sent to the corresponding channel. The email screenshot above shows the content of the message.

Custom pull request message​

The following screenshot shows an example pull request comment with a custom message.

Example pull request comment with a custom message

4. Block pull requests​

Use this option carefully. It works by failing the CI/CD pipeline that runs Infracost (infracost comment will exit 1). Depending on how you have configured your source control system this blocks the pull request from being merged, but your source control system admins can usually override this during urgent cases.

This feature only works if you are using the GitHub App integration or the infracost comment command in CI/CD.

Setup​

To setup this feature, you should:

  1. Enable the "Block pull request from being merged" option when you create the guardrail.

    Blocking pull requests

  2. If you are using the GitHub App integration, in your GitHub repository, go to Settings > Branches > and tick the "Require status checks to pass before merging" option under Protect matching branches. Otherwise ensure that your CI/CD pipeline is blocking pull requests that fail the CI/CD pipeline as infracost comment command will exit 1 when a guardrail triggers.

    Configure GitHub to require status checks to pass before pull requests can be merged

Example output​

The following screenshot shows an example pull request that has been blocked due to a guardrail that was triggered.

Example pull request being blocked due to a triggered guardrail

5. Unblock pull requests​

When a pull request (PR) is blocked by a guardrail, the email notification will now include a link to the PR page in Infracost Cloud. From there (as shown below), you can review the cost estimate, see details of the triggered guardrail, and unblock the PR.

If someone with admin access on GitHub overrides the guardrail and merges the PR, Infracost Cloud will send an additional email notification to the people subscribed to the guardrail. This provides everyone with visibility of the change, thus preventing surprises in the cloud bill.

Unblock pull requests

How Guardrails work​

The following example describes how guardrails work. Let's say you have two guardrails:

  1. A guardrail called "20 percent threshold" that notified FinOps when a pull request (PR) increases costs by more than 20%. This keeps them in the loop and avoids surprising them as this is an anticipated change being made by engineering.
  2. Another guardrail called "budget" that blocks the PR when the total cost goes over the budget, $10K/month. This enables the team lead to review and unblock the PR, and coordinate the budget increase with the management team.

When a new PR is opened that is below the threshold, both guardrails pass.

  • When new commits are added to the open PR that exceed the 20% threshold, the first guardrail triggers and notifies the FinOps team.
  • When more commits are added to the open PR that exceed the second threshold (budget), the second guardrail triggers and blocks the PR until it has been reviewed.
  • When the PR is unblocked by a team lead in Infracost Cloud, it can be merged.
  • Now if more commits are added to the open PR that increase the costs even further, the PR is not blocked by the guardrail as it has already been unblocked once. This reduces noise and prevents frustrating the engineering team as the team leads are now in the loop about the upcoming change.