Connect Workspaces with Run Triggers

Terraform Cloud's run triggers allow you to link workspaces so that a successful apply in a source workspace will queue a run in the workspace linked to it with a run trigger. For example, adding new subnets to your network configuration could trigger an update to your application configuration to rebalance servers across the new subnets.

When managing complex infrastructure with Terraform Cloud, organizing your configuration into different workspaces helps you to better manage and design your infrastructure. Configuring run triggers between workspaces allows you to set up infrastructure pipelines as part of your overall deployment strategy.

In this tutorial, you will set up one workspace to manage your network and a second workspace to manage your application. You will configure a run trigger so that any changes to your network workspace will queue an apply step on your application workspace.

»Prerequisites

This tutorial requires:

• A Terraform Cloud or Terraform Enterprise (version v202003-1 or later) account.
• You may want to create a new organization to use with this tutorial, to keep the workspaces you create separate from the rest of your infrastructure.
• A GitHub account.
• An Amazon Web Services (AWS) account, along with an "access key ID" and "secret access key" for an IAM user with permission to create VPCs, EC2 instances, and related infrastructure. You can learn more about access keys in the AWS documentation.

»Fork GitHub repositories

This tutorial uses two GitHub repositories, one for each workspace, which you will need to fork to use with your Terraform Cloud account.

»Network Repository

Navigate to the network repository. Use the "Fork" button in the upper right corner of that page to fork that repository into your account.

Inside this repository, you will find three files that make up the Terraform configuration for your network infrastructure.

• main.tf configures the aws provider, resources for your VPC, load balancer, and related networking infrastructure.
• variables.tfdeclares variables, including the region and the number of public and private subnets.
• outputs.tf declares the outputs for this module. The application workspace will use these outputs in its configuration.

»Application Repository

Next, navigate to the application repository. Again, use the "Fork" button to fork this repository into your GitHub account.

The application repository is organized like the network repository, but with one important difference — this module uses a terraform_remote_state data block at the top of main.tf to retrieve the outputs from the network workspace. Remote state data blocks allow you to share data between workspaces in Terraform Cloud. When used with the run trigger you will configure later in this tutorial, this data block will allow the application workspace to respond to changes to the network workspace.

data "terraform_remote_state" "network" {
  backend = "remote"

  config = {
    organization = var.tfc_org_name
    workspaces = {
          name = var.tfc_network_workspace_name
    }
  }
}

data "terraform_remote_state" "network" {  backend = "remote"
  config = {    organization = var.tfc_org_name    workspaces = {          name = var.tfc_network_workspace_name    }  }}

This data block resource will connect to Terraform Cloud to retrieve output values from the indicated workspace, including the subnet and load balancer configuration. Later in main.tf, you can see that the "aws_instance" "app" resource uses this data to configure the correct subnet and security groups for each EC2 instance.

  subnet_id              = data.terraform_remote_state.network.outputs.private_subnet_ids[count.index % length(data.terraform_remote_state.network.outputs.private_subnet_ids)]
  vpc_security_group_ids = data.terraform_remote_state.network.outputs.app_instance_security_group_ids

  subnet_id              = data.terraform_remote_state.network.outputs.private_subnet_ids[count.index % length(data.terraform_remote_state.network.outputs.private_subnet_ids)]  vpc_security_group_ids = data.terraform_remote_state.network.outputs.app_instance_security_group_ids

In the next section, you will create and configure workspaces for both of these repositories. Then, since the application infrastructure depends on the network infrastructure, you will set up a run trigger to connect them so that a change to your network infrastructure will reconfigure your application infrastructure as needed.

»Configure workspaces

Login to Terraform Cloud web UI. You may want to create an organization specifically for this example to separate it from any production infrastructure you are managing with Terraform Cloud. You will need this organization name when configuring the application workspace.

»Network workspace

Create the network workspace by following these steps:

1. Navigate to "Workspaces" from the top menu, and click the "New Workspace" button in the upper right corner.
2. Connect to the "learn-terraform-run-triggers-network" GitHub repository you forked in the last step.
3. The workspace name should be "learn-terraform-run-triggers-network".
4. Click the "Create Workspace" button.

It will take a few moments for Terraform Cloud to connect to GitHub and populate the workspace. While this process completes, go to the "Variables" page within your new workspace.

Terraform will authenticate with AWS using your access key ID and secret access key. Add these two values to the "Environment Variables" section, using the keys AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. Mark these variables as "sensitive".

»Application workspace

Now that you have configured the network workspace, create the application workspace by following a similar set of steps.

1. Navigate to "Workspaces" from the top menu, and click "New Workspace".
2. Connect to the "learn-terraform-run-triggers-application" GitHub repository you forked.
3. The workspace name should be "learn-terraform-run-triggers-application".
4. Click the "Create workspace" button.

Once you have created the application workspace, navigate to the "Variables" page.

The remote state data block in the application configuration requires both the organization name and workspace name. It is set up to use the workspace name "learn-terraform-run-triggers-network" by default, but your organization name will be unique.

Create a Terraform Variable with the key tfc_org_name, and set the value to the name of your Terraform Cloud or Terraform Enterprise organization. In the screenshot below, the organization name is "hashicorp-learn" — you will need to change this to your organization name.

In the Environment Variables section, set the same AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY variables as you did for the network workspace.

Now you have two workspaces, one for your network and another for your application environment.

Next, you will configure a run trigger for the application workspace. Once the run trigger is configured, whenever the network workspace completes a successful apply step, a plan will automatically be queued in the application workspace.

»Allow remote state access

Terraform Cloud protects your state file by encrypting it at rest and automatically restricting access to it from other workspaces. Allow the application workspace to access the network workspace's state by navigating to the network workspace's "Settings" page under "General". Scroll to the "Remote state sharing" section.

Under "Search for workspaces to share with" select "learn-terraform-run-triggers-application" from the drop-down menu. Save your settings.

»Configure a run trigger

From the application workspace menu, click on "Settings" and select "Run Triggers". Add a run trigger by selecting "learn-terraform-run-triggers-network" as the source workspace and clicking "Add workspace".

Now, return to the network workspace. Queue a plan for the network workspace by clicking on the "Queue plan" interface in the upper right corner of the page, followed by the "Queue plan" button.

When the plan step is finished, there will be a message telling you that a successful apply step for this workspace will trigger a run for the learn-terraform-run-triggers-application workspace.

Click "Confirm & Apply" to apply the plan.

It will take a few minutes for the apply step to complete and the network resources to be provisioned.

Once the apply step has completed, return to the application workspace. Notice that the run trigger you configured earlier has caused a new plan to be queued for this workspace. You need to manually apply all plans executed via run trigger.

Once the plan step is finished, click "Confirm & Apply" to apply the run. After the apply step is complete, click on the "Apply Finished" dropdown to see more details. Copy the value shown for public_dns_name and paste it in your web browser's address bar to see the "Hello, world!" message from the application.

Now that you have set up a run trigger between your two workspaces, a successful apply on the network workspace will queue a plan on the application workspace. You can use run triggers to coordinate between workspaces as part of your infrastructure pipelines with other automation tools.

»Clean up

Destroy the infrastructure provisioned in these example workspaces to avoid unexpected charges from AWS. You must destroy this infrastructure in the correct order, because the VPC and associated infrastructure provisioned by the network workspace cannot be destroyed while there are EC2 instances provisioned by the application workspace which depend on it.

First, visit the application workspace, and from the Settings menu, choose "Destruction and Deletion". Ensure that the "Allow destroy plans" checkbox is checked. Next, click the "Queue destroy plan" button, and follow the steps to queue and confirm a destroy step.

Once the infrastructure has been successfully destroyed, you can return to the "Destruction and Deletion" page to delete the application workspace.

Second, queue and apply a destroy plan for the network workspace by following the same steps. Optionally, you can delete the network workspace as well.

You may also want to delete the AWS IAM user you created in the Prerequisites section.

Finally, if you wish you can also delete the two GitHub repositories you forked earlier.

»Next Steps

Infrastructure and application developers have common goals including automating integration and application delivery pipelines. Run triggers are one of the ways Terraform Cloud supports infrastructure pipelines to satisfy the unique needs of infrastructure teams.

»Further Reading

• Read more about run triggers and future plans for infrastructure pipelines in this blog post.
• Learn more in the documentation for run triggers and Remote State data sources.
• See how to automate run triggers using the Terraform Cloud API.
• Now that you are comfortable using run triggers, try a more in-depth tutorial and Deploy Consul and Vault on a Kubernetes Cluster using Run Triggers.