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 (summary, plan, guardrails, and cost) 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 base callback URL (for TFC/E to call Terracotta)
     • A signing secret (used to validate requests)

2. Add Terracotta Run Tasks to Terraform Cloud
   You can create one or more run tasks in TFC/E, each pointing to a specific Terracotta endpoint:

   a. Summary (Post-Plan Summary)

   • In Terraform Cloud/Enterprise, go to your organization’s Settings → Run Tasks.
   • Click Create run task.
   • Enter:
     • Name: Terracotta Summary
     • URL: base callback URL from Terracotta, with /summary suffix
       (for example: https://api.tryterracotta.com/v1/hcp/summary)
     • HMAC Key: Use the signing secret provided by Terracotta
   • Choose enforcement level (Advisory or Mandatory).
   • Attach this run task to workspaces at the post-plan stage.

   b. Plan (Post-Plan Analysis)

   • Create another run task:
     • Name: Terracotta Plan
     • URL: base callback URL with /plan suffix
       (for example: https://api.tryterracotta.com/v1/hcp/plan)
     • HMAC Key: same signing secret
   • Attach at the post-plan stage.

   c. Guard (Post-Plan Guardrails)

   • Create another run task:
     • Name: Terracotta Guard
     • URL: base callback URL with /guard suffix
       (for example: https://api.tryterracotta.com/v1/hcp/guard)
     • HMAC Key: same signing secret
   • Attach at the post-plan stage.

   d. Cost (Post-Plan Cost Analysis)

   • Create another run task:
     • Name: Terracotta Cost
     • URL: base callback URL with /cost suffix
       (for example: https://api.tryterracotta.com/v1/hcp/cost)
     • HMAC Key: same signing secret
   • Attach at the post-plan stage.

3. Attach the Run Tasks to Workspaces

   • Go to each workspace you want analyzed.
   • Under Settings → Run Tasks, attach the Terracotta run tasks you created.
   • Choose at which stages they should run:
     • post-plan → runs Terracotta Summary (/summary)
     • post-plan → runs Terracotta Plan (/plan)
     • post-plan → runs Terracotta Guard (/guard)
     • post-plan → runs Terracotta Cost (/cost)

What Terracotta Analyzes

Terracotta HCP run tasks currently support:

• Post-Plan (Summary)

  • Runs tcSummaryAPI against the Terraform plan JSON (treated as a “file”) to produce:
    • High-level description of what the plan is about to do
    • Key changes and risks explained in plain language

• Post-Plan (Plan Analysis)

  • Runs tcPlanAPI to check the Terraform plan for:
    • Security issues
    • Compliance violations
    • Best practice gaps

• Post-Plan (Guardrails)

  • Runs tcGuardAPI using your configured guardrails to detect:
    • Violations of internal policies
    • Org-specific safety/compliance rules
    • Misconfigurations that contradict your guardrail corpus

• Post-Plan (Cost Analysis)

  • Runs tcCostAPI in plan mode to analyze the cost impact of the proposed changes:
    • Per-resource or per-change cost impact
    • Notable increases or decreases
    • Potential spend risks

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, etc.)
• Status (Normal or Speculative run)
• Description of the issue or finding
• Recommendation to fix or mitigate it

For Plan and Guard checks:

• Runs fail if blocking issues exist and the run task is Mandatory
• Runs continue with warnings if Advisory

For Cost and Summary:

• Results are typically informational
• You may configure them as Mandatory if desired

Troubleshooting

• Run task shows “unprocessable entity” (422):
  Ensure you’ve copied both the callback URL (with the correct /summary, /plan, /guard, or /cost suffix) and HMAC key exactly from Terracotta.

• No outcomes showing in Terraform Cloud:
  Check Terracotta logs to confirm:

  • Requests are being received
  • Signatures validate
  • They hit the expected HCP endpoint

• 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