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 prevention

We figure out how much you've saved on guardrails by looking at the difference between the costliest run that activated the guardrail and the final cost when you made your latest change. So, let's say an engineer opens a pull request with a change that would've increased the cost by $10k, but the guardrail is triggered. Your team then works to reduce the cost, and the changes finally get approved and merged with an increased cost of $2k. In this case, you've saved $8k because of the guardrail.

From the Infracost Cloud dashboard, you can see the total cost prevention from guardrails. Clicking on that number will show you an audit trail of the pull requests and their cost prevention numbers.

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 Governance > Guardrails page.

1. Scope of 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).

2. Pull requests to monitor

Usually users monitor all pull requests for the guardrails. However, you can also set filters, e.g. only monitor pull requests in certain repositories.

3. Thresholds

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

1. Diff: Cost change: triggered when costs are increased by more than this value, which protects against unexpected cost spikes. For example, trigger a guardrails whenever a pull request adds more than $2000 to the monthly costs.
2. Diff: Cost change percentage: similar to the above but using a percentage instead of a fixed value. For example, trigger a guardrails whenever a pull request adds more than 25% to the monthly costs.
3. Budget: New monthly cost: triggered when the new monthly cost exceeds this value, which protects against budgets being exceeded. For example, trigger a guardrails whenever the new monthly cost exceeds $10,000.

4. 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. 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.

Email

The following screenshot shows an example email notification.

Slack

The following screenshot shows an example Slack notification.

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.

5. Block pull requests

This feature prevents pull requests from being merged by signaling to your source control system (e.g., GitHub) that a pull request check has failed. While Infracost handles the failure notification, you must configure your source control system to block merges when status checks fail. In urgent cases, source control system admins can usually override these settings.

To set up this feature, follow the steps below based on your source control system:

1. Enable Blocking in Infracost: In Infracost, enable the "Block pull request from being merged" option when creating the guardrail.

   

2. Configure Your Source Control System: Configure your source control system to require the Infracost status check to pass before merging pull requests.

   GitHub App:

   1. Infracost needs to be marked as a Required Check in GitHub. The way that can be done for a single repository is in GitHub > Settings > Branches > and tick the "Require status checks to pass before merging" option under Protect matching branches. See the following step on how this can be done in enterprises with many code repos.
   2. GitHub's Rulesets feature can be used to make Infracost a required status check across all of your repos in your organization. The docs for this are here. This docs section describes how rulesets interact at the organization and repo level.

   Azure Repos App:

   1. Go to Project Settings > Repositories > Policies
   2. Add a new or edit the existing Branch Policy for your default branches
   3. Add a new Status Check for checks/infracost, and set it to Required.

   GitLab App:

   1. Follow this doc to setup a similar configuration.

Example output

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

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 or GitLab 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.

How Guardrails work

Cost thresholds are currency-independent, a guardrail with a threshold of 2000 would be triggered by a pull request that increases your monthly costs by $2001 or €2001.

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.