»Run Tasks Integration

Note: Run Tasks is a paid feature, available as part of the Team & Governance upgrade package. Refer to Terraform Cloud pricing for details.

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.

Refer to the Run Task Integration API for the exact payload specification.

{
  "payload_version": 1,
  "access_token": "4QEuyyxug1f2rw.atlasv1.iDyxqhXGVZ0ykes53YdQyHyYtFOrdAWNBxcVUgWvzb64NFHjcquu8gJMEdUwoSLRu4Q",
  "stage": "post_plan",
  "is_speculative": false,
  "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"
}

{
  "payload_version": 1,
  "access_token": "4QEuyyxug1f2rw.atlasv1.iDyxqhXGVZ0ykes53YdQyHyYtFOrdAWNBxcVUgWvzb64NFHjcquu8gJMEdUwoSLRu4Q",
  "stage": "post_plan",
  "is_speculative": false,
  "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:

Refer to the Run Task Integration API for the exact callback specification.

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

{
  "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:

Screenshot: a diagram of the user and data flow for a Terraform Cloud run task

»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-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"

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

»HCP Packer Run Task

Hands On: Try the Set Up Terraform Cloud Run Task for HCP Packer, Standard tier run task image validation, and Plus tier run task image validation tutorials on HashiCorp Learn to set up and test the Terraform Cloud Run Task integration end to end.

Packer lets you create identical machine images for multiple platforms from a single source template. The HCP Packer registry lets you track golden images, designate images for test and production environments, and query images to use in Packer and Terraform configurations.

The HCP Packer validation run task checks the image artifacts within a Terraform configuration. If the configuration references images marked as unusable (revoked), the run task fails and provides an error message containing the number of revoked artifacts and whether HCP Packer has metadata for newer versions. For HCP Packer Plus registries, run tasks also help you identify hardcoded and untracked images that may not meet security and compliance requirements.

To get started, create an HCP Packer account and follow the instructions in the HCP Packer Run Task documentation.

»Run Tasks Technology Partners

»Aqua Security

Aqua Security’s Trivy integrates with Terraform Cloud run tasks to allow teams to identify, classify, and understand issues in the plan phase - including misconfigurations, compliance violations, and best practices checks.

To get started, sign up for the Trivy Run Tasks for Terraform Cloud integration, and follow the instructions in the Terraform Cloud Run Tasks 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.

»Firefly

Firefly integrates with Terraform Cloud to help you move faster without breaking your cloud. The run tasks integration helps teams cast a cloud safety net and understand how changing untargeted assets will affect your cloud before you deploy it.

To get started, create a Firefly account and follow the Terraform Cloud Run Tasks guide in the Firefly 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.

»Kion

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

To get started, sign up for a 30-Day free trial, and follow the instructions in the Terraform Cloud Run Task Integration user documentation.

»Lightlytics

From security checks to any additional dependency changes, the Lightlytics run task integration provides visual pending changes to your infrastructure.

To get started, sign up for a free trial, and follow the instructions in the Terraform Cloud Run Tasks Integration user documentation.

»Moderne

Moderne.io provides customers with an intuitive view for searching, analyzing, and transforming code across their entire organization.

To get started, request early access at Moderne.io, and follow the instructions in the Terraform Cloud integration user documentation.

»oak9

oak9 dynamically secures your Infrastructure as Code (IaC) and deployed cloud native workloads using built-in cloud native security for application designs, allowing you to innovate and develop quickly.

To get started, follow the instructions in the Terraform Cloud integration user documentation.

»Snyk

The Snyk integration for 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.

Hands-on: Try the Configure Snyk Run Task in Terraform Cloud tutorial on HashiCorp Learn.

»Sophos

Sophos Factory works with Terraform Cloud run tasks to enable IaC security tools including OPA, BridgeCrew’s Checkov, Accurics, TerraScan through a public solution catalog of prebuilt DevSecOps pipelines. To get started, follow the Integrate with Terraform Cloud tutorial in the Sophos documentation.

»Styra

Styra DAS works with Terraform Cloud to ensure that plans for an apply action are always evaluated against your DAS Terraform OPA policies. To get started, refer to the Terraform Cloud content in the Styra documentation.

»Tenable

Tenable.cs and Hashicorp Terraform Cloud enables teams to codify cloud security policies for infrastructure as code with automated enforcement and remediation recommendations as part of their development workflow. This lets you establish compliance and security guardrails in the development process that ensure infrastructure is secure before it is provisioned. To get started, follow the Configure Terraform Cloud Integration guide in the Tenable documentation.

»Torq

Torq is a no-code automation platform for security teams. Limitless connectivity, a visual drag-and-drop editor, and hundreds of templates aligned with industry benchmarks make it easy to automate even the most complex process. Torq and Terraform Cloud integration enables users to manage their primary resources directly from Torq workflows.