» Run Tasks Integration

In addition to using existing technology partners integrations, HashiCorp Terraform Cloud customers can build their own custom run task integrations. Custom integrations have access to plan details in between the plan and apply phase, and can display custom messages within the run pipeline as well as prevent a run from continuing to the apply phase.

» Prerequisites

To build a custom integration, you must have a server capable of receiving requests from Terraform Cloud and responding with a status update to a supplied callback URL. When creating a run task, you supply an endpoint url to receive the hook. We send a test POST to the supplied URL, and it must respond with a 200 for the run task to be created.

This feature relies heavily on the proper parsing of plan JSON output. When sending this output to an external system, be certain that system can properly interpret the information provided.

» Integration Details

When a run reaches the appropriate phase and a run task is triggered, the supplied URL will receive details about the run in a payload similar to the one below. The server receiving the run task should respond 200 OK, or Terraform will retry to trigger the run task.

{
  "payload_version": 1,
  "access_token": "4QEuyyxug1f2rw.atlasv1.iDyxqhXGVZ0ykes53YdQyHyYtFOrdAWNBxcVUgWvzb64NFHjcquu8gJMEdUwoSLRu4Q",
  "task_result_id": "taskrs-2nH5dncYoXaMVQmJ",
  "task_result_enforcement_level": "mandatory",
  "task_result_callback_url": "https://app.terraform.io/api/v2/task-results/5ea8d46c-2ceb-42cd-83f2-82e54697bddd/callback",
  "run_app_url": "https://app.terraform.io/app/hashicorp/my-workspace/runs/run-i3Df5to9ELvibKpQ",
  "run_id": "run-i3Df5to9ELvibKpQ",
  "run_message": "Triggered via UI",
  "run_created_at": "2021-09-02T14:47:13.036Z",
  "run_created_by": "username",
  "workspace_id": "ws-ck4G5bb1Yei5szRh",
  "workspace_name": "tfr_github_0",
  "workspace_app_url": "https://app.terraform.io/app/hashicorp/my-workspace",
  "organization_name": "hashicorp",
  "plan_json_api_url": "https://app.terraform.io/api/v2/plans/plan-6AFmRJW1PFJ7qbAh/json-output",
  "vcs_repo_url": "https://github.com/hashicorp/terraform-random",
  "vcs_branch": "main",
  "vcs_pull_request_url": null,
  "vcs_commit_url": "https://github.com/hashicorp/terraform-random/commit/7d8fb2a2d601edebdb7a59ad2088a96673637d22"
}

Once your server receives this payload, Terraform Cloud expects you to callback to the supplied task_result_callback_url using the access_token as an Authentication Header with a jsonapi payload of the form:

{
  "data": {
    "type": "task-results",
      "attributes": {
        "status": "passed",
        "message": "Hello task",
        "url": "https://example.com"
      }
  }
}

Terraform Cloud expects this callback within 10 minutes, or the task will be considered to have errored. The supplied message attribute will be displayed in Terraform Cloud on the run details page. The status can be passed or failed.

Here's what the data flow looks like:

» Securing your Run Task

When creating your run task, you can supply an HMAC key which Terraform Cloud will use to create a signature of the payload in the x-tfc-run-task-signature header when calling your service.

The signature is a sha512 sum of the webhook body using the provided HMAC key. The generation of the signature depends on your implementation, however an example of how to generate a signature in bash is provided below.

$ echo -n $WEBHOOK_BODY | openssl dgst -sha512 -hmac "$HMAC_KEY"

» Run Tasks Technology Partners

» Snyk

Snyk’s integration with Terraform Cloud allows teams using Terraform to find, track, and fix security misconfigurations in their cloud infrastructure as part of their SDLC before they ever reach production.

To get started, create a free Snyk account and follow the instructions in the Integrating Snyk with Terraform Cloud user documentation.

» Bridgecrew

Bridgecrew helps teams address security and compliance errors in Terraform as part of each and every code review.

To get started, sign up for an eligible pricing plan, and follow the instructions in the Integration via Run Tasks user documentation.

» Infracost

Infracost allows for cloud infrastructure costing, initiated right from a PR or Terraform run.

To get started, sign up for the Infracost Terraform Cloud integration, and follow the instructions in the Terraform Cloud Run Tasks user documentation.

» cloudtamer.io

When using cloudtamer.io, customers can choose to focus on cost savings or compliance findings on an active account.

» Lightlytics

From security checks to any additional dependency changes, Lightlytics’s integration provides visual pending changes to your infrastructure.

» Refactr

Refactr’s integration allows for users to build workflows for multiple use cases including but not limited to code scanning.