Terraform Cloud run tasks let you customize your Terraform Cloud workflow by integrating third-party tools such as vulnerability scanners, cost management, code scanning, and more into the infrastructure provisioning process. Run tasks send details about a Terraform run to external tools between the plan and apply stages of a run. The external tools run against the plan contents and return a status response with the results. Based on the response, you can configure your Terraform Cloud run task to continue or halt the run.
In this tutorial, you will create a Terraform Cloud run task for Snyk, an external policy-as-code service, to detect an overly permissive AWS security group in a run’s planned resources. You will configure a Snyk integration for Terraform Cloud and create a corresponding run task in your Terraform Cloud organization to learn how run task integrations such as Snyk can help you identify and mitigate security misconfiguration in your infrastructure.
Tip: This tutorial uses run tasks, which are available in the Terraform Cloud Team & Governance tier. Organization owners can enable a 30-day free trial in their settings under Plan & Billing.
This tutorial assumes you have completed the Terraform Cloud Getting Started Tutorial and you are familiar with the standard Terraform workflow. If you are not familiar with either, complete the Terraform Get Started and Terraform Cloud Get Started tutorials first.
You will also need:
Note: This tutorial assumes that you are using a tutorial-specific Terraform Cloud organization with a global variable set of your AWS credentials. Review the Create a Credential Variable Set for detailed guidance.
»Get Snyk credentials for Terraform
Sign in to your Snyk account and navigate to the Integrations page. Search
terraform and select the
Snyk will display your account credentials that you will use to configure the integration in Terraform Cloud. Keep this page open. In the next section, you will use these credentials to connect your Snyk account to your Terraform Cloud organization.
»Create a run task
Snyk’s infrastructure-as-code checks have a default set of security policies that check for common vulnerabilities and misconfigurations across cloud providers. In this tutorial, you will trigger Snyk’s checks for overly permissive ingress rules on AWS security groups.
In a new browser window, navigate to your Terraform Cloud
account. Navigate to the Run tasks section of
your organization settings and click Create run task. Name the run task
learn-run-tasks-snyk and leave the Enabled option checked. Then, paste in
the Endpoint URL and HMAC key from the Snyk browser window you left open in the
previous step. Finally, click Create run task.
»Create an example workspace
Fork the example repository for this tutorial. This repository contains Terraform configuration for an overly permissive security group that allows global ingress SSH traffic.
Next, create a VCS-driven Terraform Cloud workspace connected to your
Tip: If you have not yet configured your Github integration with Terraform Cloud, review the VCS-driven workflow tutorial. If you are using an alternative VCS provider, review the documentation for configuration guidance.
»Associate run task with workspace
Navigate to your workspace’s run task settings and select the learn-run-tasks-snyk card.
Run tasks have two enforcement levels: advisory and mandatory.
- Advisory run tasks will notify if they fail during a run, but still allow users to apply the execution plan. You could use an advisory enforcement level to confirm acceptable but not ideal changes, such as over-provisioned capacity on a resource in a development environment.
- Mandatory run tasks stop the run if they fail. You could use a mandatory enforcement level to ensure users do not violate non-negotiable organizational policies, such as public-read buckets.
You can set different enforcement levels on a run task in each workspace it is associated with.
Set the Enforcement Level to
Advisory and click Create.
»Trigger a run task failure
From the Actions menu in your workspace, select Start new run, then Start run. After Terraform determines the execution plan, it will perform the run task.
Though the security group you attempted to provision allows global ingress and fails the Snyk policy, the run task passes because you chose the Advisory enforcement level. You still have the option to apply the configuration.
To get more information about the run task failure, follow the Details link to visit Snyk.
Snyk displays the reason for the failure, the severity, and some options for resolving the issue.
Go back to the Terraform Cloud UI and discard the run before moving on.
»Change run task enforcement level
While you may wish to allow advisory run tasks in experimental development environments, in production you may want to lock down provisioning to prevent introducing vulnerabilities. To do so, you will change the run task enforcement level to mandatory.
Navigate back to your workspace run task settings. Next to the
learn-run-tasks-snyk run task, select ..., then Configure.
Change the enforcement level to Mandatory, then click Save.
Now, trigger another run in the workspace.
This time, since the run task step failed, Terraform Cloud does not allow you to apply the run.
»Clean up workspace
Since you discarded the first run, your workspace has not provisioned any resources for you to destroy.
learn-terraform-cloud-run-tasks-snyk Terraform Cloud workspace.
You must first destroy any associated workspaces before deleting a run task.
Deleting a workspace does not delete the run tasks it uses.
If you do not plan to continue using the run task, delete it as well. After
deleting your workspace, navigate to your Terraform Cloud organization’s
settings, then select Run Tasks in the sidebar. Find your
learn-run-tasks-snyk run task and click ... then Edit.
At the bottom of the run task details page, click Delete run task, then confirm by clicking Yes, delete task.
In this tutorial, you learned how to configure a Terraform Cloud run task for Snyk. You also reviewed the differences between the advisory and mandatory enforcement levels for run tasks.
- Review the documentation for creating your own run task.
- Learn how to control your infrastructure costs using Terraform Cloud.
- Learn how to use Sentinel for policy enforcement.