Terraform Cloud Run task

Protect your infrastructue by detecting potential issues in your Terraform configuration and plan before applying the changes to production!

NOTE! the instructions on this page are identical for Terraform Enterprise users as well.

Run tasks stages

Spectral can be integrated with Terraform cloud in two stages of the Terraform run:

Pre-plan

This stage takes place right before the plan stage.
In this stage, Spectral would scan your Terraform configuration deployed in this run for misconfigurations.

Post-plan

This stage takes place between the plan and apply stages.
In this stage, Spectral would scan the generated plan of the current run for potential issues before applying the changes to your live infrastructure.
You can read more about run tasks in Terraform Cloud here and here.

Integration Environment Variables

VariableRequiredDescription
SPECTRAL_DSNYesYour Spectral DSN retrieved from SpectralOps
CHECK_POLICYYesIf Spectral finds issues - how should we handle the run? The policies are based on the Spectral issue severity - critical / high / medium / low / informational (Valid values: "Fail on any issue" / "Fail on low and above" / "Fail on medium and above" / "Fail on high and above" / "Fail on critical only" / "Always Pass")
HMAC_KEYYesA key that will be used for securing your Run Task by validating the request payload signature, should be identical to the HMAC key you set will set in the Run Task
TERRAFORM_USER_KEYNoUser key created by Terraform (required for pre-plan run task) - can be created here

Setup

This integration is based on an AWS lambda function which is being triggered by the Run Task at the relevant stage.
The setup process of a Spectral run task has several steps:

1. AWS Lambda Setup

Create the required AWS resources in one of of the following methods:

Make sure to supply all the required environment variables, including SPECTRAL_DSN, CHECK_POLICY and HMAC_KEY.
In case you are about to create a pre-plan Run Task, please create a user API key in Terraform, and then set this key in the TERRAFORM_USER_KEY env variable.
After resources creation is finished, grab the gateway api URL (if you are using the terraform module - use rest_api_url output), we`ll use it later.

2. Create Run Task in Terraform Cloud

For creating a new Run Task please do the following: Get into your organization in Terraform Cloud and click on Settings at the top menu:

And then create the "Create run task" button:

Then, in the new run task form, enter the name and description values, paste the API Gateway URL from the previous step in the "Endpoint URL" field:

For securing your Run Task, please type the exact same key you had set into the HMAC_KEY environment variable in the previous step. This is mandatory for the Spectral integration to work, although it shows up as optional in Terraform Cloud.

When done, click on Create run task button. The Spectral Run Task has been created and is ready to use.

3. Add the Run Task to your workspace

Go to your workspace settings by clicking on the "Settings" button:

Then, in the Run Tasks configuration page select the required stage and set the Enforcement Level to Mandatory to make sure the run is stopped while Spectral detects issues:

Click save, and you're done!

4. Trigger a run!

Trigger a run to make sure everything is well configured. If everything is OK - you should see new step on the run page according to the run task stage you selected.

New Pre-plan step in Terraform

New Post-plan step in Terraform