Skip to main content

Use Styra DAS with Terraform Cloud

To connect Styra DAS with your Terraform Cloud organization, Styra DAS needs to create a run task in your Terraform Cloud organization to allow for secure communication with Terraform Cloud. This run task gets associated with individual Terraform Cloud workspaces to allow Styra DAS to receive an API request from Terraform Cloud in the post-plan stage of a workspace run.

note

While the Styra DAS Free and DAS Enterprise plans both include support for the run task integration with Terraform Cloud, the run tasks feature in Terraform Cloud is available only to Terraform Cloud organizations on a Team & Governance or Business plan.

If your organization is currently using the Terraform Cloud free plan, you can upgrade to the Team & Governance plan trial in your Terraform Cloud organization billing settings to gain access to the run tasks feature in Terraform Cloud for the duration of your Team & Governance plan trial.

Generate a Terraform Cloud Organization API Token

Run tasks are managed at the Terraform Cloud organization level and require a user with organization owner permissions. You will need to provide Styra DAS with a temporary Terraform Cloud organization API token, which allows Styra DAS to create the run rask in your organization. The provided Terraform Cloud organization API token is only used for this one-time integration and will not be stored by Styra DAS.

info

Terraform Cloud organization API Tokens are a type of token intended for initial setup tasks within your organization. Organizations can have only one valid organization API token active at any one time and should rotate the token after each one-time use.

Refer to Terraform Cloud's Organization API Tokens documentation for additional details.

To generate the organization API token:

  1. Log in to the Terraform Cloud console at app.terraform.io.
  2. Click Settings in the navigation bar.
  3. Click API Tokens from the left-hand menu.
  4. Click the Create an organization token button.
  5. Copy the organization token value for the next step. The token value will not be shown again if you navigate away in the Terraform Cloud console.
note

If an organization token has been previously generated, you will see a Regenerate token button instead of a create button. Ensure the existing token's use is no longer needed for other setup tasks/integrations, then click the regenerate button and the Yes, Regenerate Token in the confirmation modal.

Connect Styra DAS to Terraform Cloud

Styra DAS automates the integration process with Terraform Cloud by creating an organization-level run task and securing it with a private HMAC Key to validate run task API requests for your specific Styra DAS workspace.

To start the automated integration process:

  1. In the Styra DAS UI, click on your workspace in the left-hand navigation menu under WORKSPACE. Go to your workspace's Settings >> Terraform Integration pane and enter in the following information:

    • Terraform Cloud Organization: Enter your Terraform Cloud organization name (case sensitive) as used in Terraform Cloud. You can find your organization name displayed in the top-left of the Terraform Cloud console, or refer to Terraform Cloud's Organization Settings documentation for details on how to find your organization name.

    • Terraform Cloud API token: Enter your Terraform Cloud organization API Token generated in the section above. This token will only be used in this setup process and will not be saved by Styra DAS.

  2. Click the Save changes button.

    Once the integration has been successfully created, you should see the Terraform Cloud organization URL for your organization and the Terraform Cloud run-task URL for the run task created by Styra DAS.

Add a Run Task to a Terraform Cloud Workspace

Once Styra DAS has created the run task at the Terraform Cloud organization level, you can associate the Run Task with Terraform Cloud workspaces. Refer to Terraform Cloud's Associating Run Tasks with a Workspace documentation for full details of this process. A summary of these steps is included below.

  1. In Terraform Cloud, navigate to the desired workspace and click the workspace-level Settings >> Run Tasks.

  2. Select the Styra DAS run task created by Styra DAS from the Available Run Tasks. The Styra DAS run task will be named in the format styra-das-policy-check-<DAS_tenant>.

  3. Select the policy check's enforcement level ("mandatory" or "advisory"). A mandatory enforcement level (recommended) will prevent Terraform Cloud workspace runs with "enforce" policy evaluation failures from apply changes to cloud resources (Styra DAS "monitor" policy rules will not block workspace run completion).

  4. Click the Create button.

important

To associate run tasks to workspaces in Terraform Cloud, your user requires workspace administrator permissions.

Associate a Styra DAS System with Terraform Cloud Workspaces

To define policies to evaluate on Terraform Cloud workspace runs, you associate a Styra DAS Terraform system and its policies with one or more Terraform Cloud workspaces. This mapping association is set in your Styra DAS workspace settings:

  1. In your Styra DAS workspace's Terraform Integration settings, click the Add system mapping button and define the following:

    • DAS Terraform system: From the dropdown, select a Terraform system in your Styra DAS account.
    • Terraform Cloud workspaces: Enter the Terraform Cloud workspace ID for the workspace with the run task added in the section above. This field accepts multiple workspace IDs to allow you to map a Styra DAS Terraform system and its policies to multiple workspaces.
  2. Press Enter after entering each workspace ID.

  3. Click the Save changes button.

Once added, your Styra DAS Terraform system to Terraform Cloud workspace mappings are shown in this workspace settings pane as well as at the system level.

You can verify your Terraform system is mapped to the specified Terraform Cloud workspace(s) by navigating to your Terraform system and clicking on Settings >> Terraform Cloud. The Terraform Cloud pane displays a configuration message with the current status of any mappings of Terraform Cloud workspaces to this Styra DAS system.

Figure 1 - Terraform Cloud System MappingFigure 1 - Terraform Cloud System Mapping

important

If you need to change the system associated with a Terraform Cloud workspace, you must first delete the system mapping by clicking on the trash can 🗑 icon and then add a new system by clicking on the Add system mapping button.

Styra DAS Decision Log Mappings for Terraform Cloud Runs

If you are mapping multiple Terraform Cloud workspaces to a Styra DAS Terraform system, you can update the system's default decision mapping to display the Terraform Cloud workspace name and run ID in separate columns in the Decision Log to help you distinguish Styra DAS decisions between various workspaces and runs.

To update the default decision log mapping, follow the steps below.

  1. In your Styra DAS Terraform system, click on Settings >> Decision Mappings.

  2. Click on the existing "Default" mapping or a custom mapping you have already defined.

  3. In the Columns section, add the following two column definitions:

    Search keyPath to value
    workspaceinput["styra-tfc-webhook"].workspace_name
    run_idinput["styra-tfc-webhook"].run_id

Generate a Styra DAS Decision for a Terraform Cloud Run

Once you have your Styra DAS Terraform system (and its policies) and Terraform Cloud workspace mappings defined, trigger a workspace run via either the Terraform Cloud UI or via the Terraform CLI.

Once the plan phase of the run is complete, the Styra DAS run task will evaluate the plan against your Styra DAS Terraform system policies. The Styra DAS policy evaluation result summary will be displayed in the Terraform Cloud run details as well as in the Terraform CLI, if used.

Figure 2 - Terraform Cloud Run DetailsFigure 2 - Terraform Cloud Run Details

The Details link on the Styra DAS run task will navigate you directly to the associated policy decision in Styra DAS.

important

You must have Terraform CLI version 1.1.9 or higher to receive run task result details within the CLI.