Set up run task integrations

In addition to using existing technology partners integrations, HashiCorp HCP Terraform 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 HCP Terraform 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",
  "capabilities": {
    "outcomes": true
  },
  "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, HCP Terraform 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": "running",
        "message": "Hello task",
        "url": "https://example.com",
        "outcomes": [...]
      }
  }
}

The request errors if HCP Terraform does not receive a progress update within 10 minutes or if the request runs for more than 60 minutes. HCP Terraform displays the supplied message attribute on the run details page. The status is either running, passed, or failed.

Here's what the data flow looks like:

Refer to the run task integration API for the exact payload specifications, and the run task JSON schema for code generation and payload validation.

Securing your Run Task

When creating your run task, you can supply an HMAC key which HCP Terraform 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 HCP Terraform 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 HCP Terraform 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.