# HCP Terraform run task

> Page: https://docs.plotwork.dev/hcp-terraform-run-task. Index of every page: https://docs.plotwork.dev/llms.txt

The HCP Terraform run task draws every plan a workspace makes. HCP Terraform, or Terraform Enterprise, calls Plotwork after the plan; Plotwork reads the plan, draws the planned infrastructure into your organisation's private library, and reports back to the run with a link to the diagram. Each change shows in its colour: what is created, changed in place, replaced, or destroyed.

## TL;DR

| Question | Answer |
|---|---|
| Which plan? | Pro and Enterprise, the plans with the drift dashboard. |
| Who sets it up? | In Plotwork, the organisation's owner or an admin, under Keys and CI. In HCP Terraform, someone who can manage run tasks for the organisation. |
| What does HCP Terraform need? | The endpoint URL and the HMAC key the portal shows. |
| Which stage? | Post-plan. |
| Does it block a run? | No. Plotwork reports passed by default, and the run task is attached as Advisory. |
| Where do the diagrams go? | The organisation's private library, in the folder `HCP Terraform/<workspace>`. A character a folder name cannot hold becomes `-`, so `shop.prod` is filed in `HCP Terraform/shop-prod`. Each run draws over the workspace's diagram, and the picture before is kept as a previous version. |
| What does Plotwork store? | The published diagram and an audit event for each run. Never the plan, the run's token, or a variable. |
| Does Terraform Enterprise work? | Yes. It speaks the same run task protocol. |

## Owner and admin steps

### 1. Turn it on in Plotwork

1. In the portal, open the organisation, choose Keys and CI, then Terraform. The address `/orgs/<handle>/keys?view=terraform` opens it too.
2. Open the HCP Terraform run task card and choose Turn on.
3. Copy the endpoint URL and the HMAC key. The key shows once here; Show key brings it back later, for the owner and admins only.

```film
slug: hcp-terraform-run-task
```

### 2. Create the run task in HCP Terraform

1. In HCP Terraform, open Organization settings, then Run tasks.
2. Choose Create run task.
3. Name it `Plotwork`.
4. Paste the endpoint URL into Endpoint URL.
5. Paste the HMAC key into HMAC key.
6. Leave Source as Managed, and choose Create.

HCP Terraform checks the address when you create the run task. Plotwork answers that check and nothing else happens.

### 3. Attach it to each workspace

1. Open the workspace, then Settings, then Run tasks.
2. Next to Post-plan, choose Add run task, and pick `Plotwork`.
3. Choose Advisory as the enforcement level, and save.

The next plan of that workspace is drawn. Open the run, and the Plotwork task result links to the diagram.

## What a run does

| Step | What happens |
|---|---|
| The request | HCP Terraform posts the run to the endpoint, signed with the HMAC key in `X-TFC-Task-Signature`. Plotwork checks the signature over the exact body before it reads anything, and answers at once. |
| The plan | Plotwork reads the plan's JSON from HCP Terraform with the run's own access token. The token goes to HCP Terraform only. |
| The drawing | The `terraform-plan` importer draws the planned stack, each change marked, the same drawing `import_source` makes from `terraform show -json`. |
| The library | The diagram is published as "HCP Terraform" to `HCP Terraform/<workspace>`, named `<workspace> plan`. A speculative plan, such as one for a pull request, is a diagram of its own, `<workspace> speculative plan`. Every rule of the library applies: folder rules, locks, secret scanning, classification labels, and publishing approval. |
| The result | Plotwork sends `passed` to the run with one sentence and the link to the diagram. |

A run Plotwork cannot draw or keep, such as a plan it cannot read or a library at its limit, is reported as passed with a sentence that says why. Tick "Report a plan Plotwork cannot draw as failed" on the card to report it as failed instead. With an advisory run task the run goes on either way; choose Mandatory in the workspace only if a failed drawing should stop the apply.

## The HMAC key

| Action | What happens |
|---|---|
| Show key | Shows the key again to the owner or an admin. Recorded in the audit log, never with the key. |
| Rotate key | Makes a new key. The old one stops working at once, so edit the run task in HCP Terraform and paste the new key. |
| Turn off | Deletes the key, so every request is refused. The diagrams stay in the library. Remove the run task in HCP Terraform as well. |

Plotwork keeps the key sealed with AES-256-GCM under a server secret, bound to your organisation. A request without a signature, or with one that does not match, is refused with 401.

## Audit events

| Event | When |
|---|---|
| `orgs.run_task.enable` | The run task was turned on. |
| `orgs.run_task.reveal` | The key was shown again. |
| `orgs.run_task.rotate` | A new key was made. |
| `orgs.run_task.update` | The failed-run option changed. |
| `orgs.run_task.disable` | The run task was turned off. |
| `orgs.run_task.run` | HCP Terraform called it for a run. The actor is the run task; the event names the run, the workspace, the stage, the status sent back, and the outcome. |

## Troubleshooting

| What you see | Why, and what to do |
|---|---|
| HCP Terraform cannot create the run task | The endpoint answered 401 or 404. Check that the run task is on in Plotwork and that the HMAC key was pasted whole. |
| The task result says the plan was not drawn | The sentence says why: the plan could not be read, it is larger than 10 MiB, or the library refused it. |
| `run_task.signature_invalid` in HCP Terraform's log | The key in HCP Terraform is not the current one. Show key, or rotate it, and paste it again. |
| The task result says the plan no longer includes it | The owner's plan has no run task. Nothing is drawn until the owner upgrades. |
| No diagram after a pre-plan run | Plotwork draws the plan, so attach the run task at Post-plan. |

## See also

| Page | Why |
|---|---|
| [Terraform in organisations](https://docs.plotwork.dev/terraform-organisations.md) | Keys for Terraform, and the design workspace |
| [Diagrams in CI](https://docs.plotwork.dev/diagrams-in-ci.md) | Drawing diagrams from the repository with the GitHub Action |
| [Organisations](https://docs.plotwork.dev/organisations.md) | Roles, folders and the private library |
| [Audit log](https://docs.plotwork.dev/audit-log.md) | Reading the run task's events |
| [Plans and billing](https://docs.plotwork.dev/plans-and-billing.md) | What Pro and Enterprise include |