Terraform Cloud cost estimation with a run task (HCP Terraform)

Quick answer

Register a post-plan run task in HCP Terraform. When a run plans, HCP Terraform calls your endpoint with a link to the plan JSON; the task downloads it, prices the resolved resources, and returns a monthly cost that shows inline in the run UI. Make it mandatory with a budget threshold and it blocks runs that would blow the budget, no cloud credentials required.

HCP Terraform (formerly Terraform Cloud) already runs your plan in a controlled place with the plan JSON right there. A run task is the native way to hook cost into that flow, so the estimate appears in the same run the reviewer is already looking at, no separate CI needed.

How run tasks fit the run lifecycle

A run task is a webhook fired at a stage of the run. For cost, the stage is post-plan: the plan exists, so there's something to price. HCP Terraform sends a payload, waits for your endpoint to reply passed or failed, and renders the message and status in the UI. Advisory tasks inform; mandatory tasks can block.

Price the plan the payload points to

The post-plan payload includes a plan_json_api_url and an access token. The run task downloads the resolved plan and estimates it, the same plan JSON that's the most accurate input anywhere else.

# inside the run task handler
curl -sSL -H "Authorization: Bearer $ACCESS_TOKEN" \
  "$PLAN_JSON_API_URL" > plan.json
c3x estimate --path plan.json --budget 500

Return the monthly total in the run task's response message, and set the status to failed when the estimate exceeds the budget.

Advisory first, then mandatory

Start the task advisory so the cost shows on every run without blocking anyone. Once the number is trusted, switch the budget gate to mandatory so a run that exceeds the threshold can't reach apply. That's the budget-guardrail pattern, native to the Terraform Cloud UI.

Where it runs

The run task endpoint is a small service you host. Because it only needs the plan URL from the payload and a pricing catalog, it works with Terraform Cloud, Terraform Enterprise, and self-hosted agents, and can run entirely inside your network, which suits air-gapped setups that also self-host the pricing catalog.

Prefer plain CI? Same idea

If you don't use run tasks, the identical estimate runs in GitHub Actions, GitLab CI, Azure DevOps, or Atlantis. The run task just moves the comment into the HCP Terraform UI.

FAQ

What is a run task in HCP Terraform?

A run task is a webhook HCP Terraform (formerly Terraform Cloud) calls at a specific stage of a run, pre-plan, post-plan, or pre-apply. It sends a payload with a link to the run's plan JSON, waits for your endpoint to respond passed or failed, and shows the result inline in the run UI.

Which stage should cost estimation run at?

Post-plan. That's the moment the plan JSON exists, so your run task can fetch it, price the resolved resources, and return a monthly cost. Pre-plan is too early (no plan yet); pre-apply also works if you only want the gate right before apply.

How does the run task get the plan to estimate?

The post-plan payload includes a plan_json_api_url. The run task calls it with the provided token to download the resolved plan, then prices that JSON, the same accurate input you'd use in any CI.

Can a run task block an expensive run?

Yes, if you set it to mandatory. A mandatory run task that returns failed when the estimate exceeds a budget stops the run from proceeding to apply. An advisory task shows the cost without blocking. Most teams start advisory and switch the budget gate to mandatory once they trust it.

Does this work with self-hosted HCP Terraform agents?

Yes. The run task endpoint is a service you host; it just needs to receive the webhook and reach the plan JSON URL and your pricing catalog. It works with Terraform Cloud, Terraform Enterprise, and self-hosted agents, and can run fully inside your network.

Do I need cloud credentials in the run task?

No. The run task prices the plan JSON against a pricing catalog; it never calls your cloud account. It needs the plan URL and token from the payload and access to a catalog, which can be self-hosted for air-gapped environments.

What to do next

Stand up a post-plan run task and see the cost appear on your next run. C3X prices the resolved plan against a live catalog and returns a monthly total with optional budget gating, free and self-hostable, so the run task can live in your own infrastructure. The quickstart and CI/CD guide have the details.