Terraform Cloud/Enterprise Run Tasks

Terracotta integrates with Terraform Cloud/Enterprise (TFC/E) via Run Tasks. This allows you to automatically analyze Terraform runs with Terracotta’s checks (plan, drift, summary, guardrails) before changes are applied.

Setup

1. Generate an HCP Run Task Integration in Terracotta

   • Navigate to your Terracotta dashboard.
   • Go to User Profile (Top Right) → Settings.
   • In the HCP Run Tasks section, create a new integration. This will generate:
     • A callback URL (for TFC/E to call Terracotta)
     • A signing secret (used to validate requests)

2. Add the Terracotta Run Task to Terraform Cloud

   • In Terraform Cloud/Enterprise, go to your organization’s Settings → Run Tasks.
   • Click Create run task.
   • Enter:
     • Name: Terracotta
     • URL: Use the callback URL provided by Terracotta
     • HMAC Key: Use the signing secret provided by Terracotta
   • Choose enforcement level (Advisory or Mandatory).

3. Attach the Run Task to Workspaces

   • Go to the workspace(s) you want analyzed.
   • Under Settings → Run Tasks, attach the Terracotta run task.
   • Select at which stages Terracotta should run:
     • post-plan → runs tcPlan

What Terracotta Analyzes

Terracotta run tasks currently support:

• Post-Plan (Plan Analysis) Runs tcPlan to check the Terraform plan for:
  • Security issues
  • Compliance violations
  • Best practice gaps

Example Output in Terraform Cloud

When a run task executes, Terracotta posts results back to Terraform Cloud. Each finding appears in the Details panel of the run:

• Severity (High, Medium, Low)
• Status (Normal or Speculative run)
• Description of the issue
• Recommendation to fix it

If blocking issues are detected:

• Runs will fail immediately if the run task is Mandatory
• Runs will show warnings but continue if Advisory

Troubleshooting

• Run task shows “unprocessable entity” (422): Ensure you’ve copied both the callback URL and HMAC key exactly from Terracotta.

• No outcomes showing in Terraform Cloud: Check Terracotta logs to confirm requests are being received and signed correctly.

• Speculative plans always marked as Advisory: This is Terraform Cloud behavior; speculative runs cannot be blocked.

Next Steps

• Guardrails – enforce org-wide compliance
• API – call Terracotta programmatically
• Best Practices – how to get the most value from Terracotta checks