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.

Available Run Tasks

You can view the most up-to-date list of run tasks in the Terraform Registry.

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

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

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

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