Skip to content
Connect an agent

Infrastructure as code

HCP Terraform run task

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

QuestionAnswer
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.
Turn on the 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

StepWhat happens
The requestHCP 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 planPlotwork reads the plan's JSON from HCP Terraform with the run's own access token. The token goes to HCP Terraform only.
The drawingThe terraform-plan importer draws the planned stack, each change marked, the same drawing import_source makes from terraform show -json.
The libraryThe 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 resultPlotwork 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

ActionWhat happens
Show keyShows the key again to the owner or an admin. Recorded in the audit log, never with the key.
Rotate keyMakes a new key. The old one stops working at once, so edit the run task in HCP Terraform and paste the new key.
Turn offDeletes 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

EventWhen
orgs.run_task.enableThe run task was turned on.
orgs.run_task.revealThe key was shown again.
orgs.run_task.rotateA new key was made.
orgs.run_task.updateThe failed-run option changed.
orgs.run_task.disableThe run task was turned off.
orgs.run_task.runHCP 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 seeWhy, and what to do
HCP Terraform cannot create the run taskThe 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 drawnThe 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 logThe 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 itThe owner's plan has no run task. Nothing is drawn until the owner upgrades.
No diagram after a pre-plan runPlotwork draws the plan, so attach the run task at Post-plan.

See also

PageWhy
Terraform in organisationsKeys for Terraform, and the design workspace
Diagrams in CIDrawing diagrams from the repository with the GitHub Action
OrganisationsRoles, folders and the private library
Audit logReading the run task's events
Plans and billingWhat Pro and Enterprise include