Spectral for Terraform Cloud

important

This integration is supported both in Terraform Cloud and Terraform Enterprise. Therefore, the instructions detailed on this page are relevant for Terraform Enterprise organizations as well.

Integrating Spectral with Terraform makes your infrastructure protected. Run Task is a paid feature in Terraform Cloud that allows 3rd parties integrate at several stages (pre & post-plan) during a Terraform run.

Run task 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 the last snapshot of your Terraform configuration for misconfigurations.

Post-plan

This stage takes place between the plan and apply stages. In this stage Spectral would scan the calculated plan of the current run for potential issues before applying the changes on your live infrastructure.

Setup

The integration setup contains three steps (both in Terraform Cloud & SpectralOps).

Step 1 - Create cloud resources required by Spectral

During the Run Task operation, it would trigger an AWS Lambda function which loads Spectral scanner and performs the scan. To create this function and the rest of the required resources for this integration, go to Terraform Cloud source page in SpectralOps, and choose one of the following:

  1. Using this Terraform module
  2. Clicking on the "Launch stack" button to create the resources via AWS cloud formation.

Make sure to supply the following environment variables:

  1. SPECTRAL_DSN - Your SpectralOps identifier, retrieved from your SpectralOps account. - Required
  2. CHECK_POLICY - Your required Check Policy - Required
  3. HMAC_KEY - A key that will be used for securing your Run Task by validating the request payload signature - Required
  4. TERRAFORM_USER_KEY - User API key published by Terraform (creating user API key can be done in this page) - Required for pre-plan integration
CHECK_POLICY (mandatory)

CHECK_POLICY responsible for setting the minimum issue severity that should fail the check. The valid values for this field are:

  1. Fail on any issue
  2. Fail on warnings and above
  3. Fail on errors only
  4. Always pass

One of the newly created resources is an API Gateway, grab its public URL (if you are using the terraform module - use rest_api_url output), so you can use it in the next step.

Step 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.

Step 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!

Step 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 Pre-plan step in Terraform
New Post-plan step in Terraform
New Post-plan step in Terraform