Link dependent workspaces

As your Terraform configuration grows and you manage more resources, splitting your configuration into multiple workspaces makes your infrastructure operations safer and more efficient. For example, if one workspace manages networking infrastructure and another manages an application that uses your networking configuration, you can configure automatic runs in the application workspace for any changes in the upstream networking workspace, as well as share data between them.

In this tutorial you will create a new workspace that uses the tfe_outputs data source to access output values from another workspace. Then, you will configure a run trigger so your new workspace starts an apply operation any time your upstream workspace finishes an apply operation.

Prerequisites

To follow this tutorial, you will need:

• An HCP Terraform account and organization
• An AWS account and associated credentials that allow you to create resources in the us-west-2 region, including an EC2 instance, VPC, and security groups.
• A GitHub account.
• The learn-hcp-terraform workspace you created in the previous tutorial.

Create example repository

Navigate to the template repository for this tutorial. Click the Use this template button and select Create a new repository. Select the GitHub account you used to configure the VCS provider and name the repository learn-hcp-terraform-run-triggers. Click Create repository to create your own copy of the repository.

This repository contains Terraform configuration to create a new AWS EC2 instance. Open the main.tf file and review the configuration.

data "tfe_outputs" "source_workspace" {
  workspace    = var.workspace_name
  organization = var.organization_name
}

resource "aws_instance" "app_server" {
  ami           = data.aws_ami.ubuntu.id
  instance_type = var.instance_type

  vpc_security_group_ids = data.tfe_outputs.source_workspace.nonsensitive_values.instance_security_group_ids
  subnet_id              = data.tfe_outputs.source_workspace.nonsensitive_values.instance_subnet

  tags = {
    Name = var.instance_name
  }
}

This configuration creates a tfe_outputs data source to get the outputs from a source workspace. The tfe_outputs data source takes in a workspace and organization, and uses the HCP Terraform API to get the outputs from the workspace. The aws_instance then references this data source to set the vpc_security_group_ids and subnet_id arguments to match the value of the source workspace.

This configuration declares two variables for the workspace name and organization name. Open the variables.tf file to review these variables.

variable "workspace_name" {
  description = "Name of the source workspace to query."
  type        = string
  default     = "learn-hcp-terraform"
}

variable "organization_name" {
  description = "Name of the HCP Terraform organization with the source workspace"
  type        = string
}

By default, this configuration queries HCP Terraform for the outputs from your learn-hcp-terraform workspace.

Generate HCP Terraform token

To share outputs from one workspace to another, you need to set the TFE_TOKEN environment variable in the downstream workspace so that it has access to the upstream workspace.

To generate a new team token, log in to HCP Terraform and navigate to your organizations Settings page. Then, choose API tokens from the left navigation panel.

Choose the Team Tokens tab, then click Create a team token.

Choose the owners team, and leave the expiration as 30 days. Click Create and HCP Terraform will show your API token. Click Copy token and save this value somewhere secure since HCP Terraform will now show this value again.

Create new workspace

Next, create a new workspace in HCP Terraform from the GitHub repository you created.

From your organization's Workspaces page, click the New drop-down, then click Workspace. Under Project, choose your Learn Terraform project, then click Create.

On the Create a new Workspace page, choose Version Control Workflow, then choose the GitHub VCS provider. Choose your learn-hcp-terraform-run-triggers repository. Leave the workspace name as learn-hcp-terraform-run-triggers and click Create.

After HCP Terraform parses your configuration, it prompts you to provide a value for the organization_name variable. Enter your HCP Terraform organization name, then click Save variables.

Next, configure the workspace to use the team token you created. Click the Go to workspace overview link, then choose Variables from the left navigation panel.

Click Add variable, and select Environment variable. Name the variable TFE_TOKEN and enter the HCP Terraform token for the value. Select the Sensitive checkbox, then click Add variable.

Configure run trigger

Because this workspace depends on your learn-hcp-terraform workspace, you can configure a run trigger so that after HCP Terraform completes an apply operation, it starts a new plan and apply operation in your learn-hcp-terraform-run-triggers workspace.

In HCP Terraform, you configure run triggers in the downstream workspaces. In your learn-hcp-terraform-run-triggers workspace, click Settings, then click Run Triggers in the left navigation panel.

Click the Connect workspace button, then click the Connect button next to your learn-hcp-terraform workspace. Click Close and ensure that HCP Terraform lists your learn-hcp-terraform workspace under Connected workspaces.

Trigger a new run

HCP Terraform only invokes a run trigger when the upstream workspace completes an apply operation. To trigger the downstream workspace, you will need to make a change to your learn-hcp-terraform workspace that will cause Terraform to change your infrastructure.

Navigate back to the overview page of your learn-hcp-terraform workspace, then click Variables. Open the ... menu for the instance_name variable, then click Edit variable.

Update the Value to learn-hcp-terraform-upstream, then click Save variable. This directs Terraform to change your instance name the next time you perform a plan and apply operation.

Click New run, then click Start to queue a new plan and apply operation. When HCP Terraform completes the plan operation, click Confirm & apply, then click Confirm plan to apply the changes.

Notice that HCP Terraform automatically queued a new run in your learn-hcp-terraform-run-triggers workspace.

Click the run ID to view the run progress. On the run summary page in your learn-hcp-terraform-run-triggers workspace, notice that it contains information about the run trigger that started this operation.

Review the plan, click Confirm & apply", then click Confirm plan** to apply the changes.

HCP Terraform lets you configure workspaces to automatically apply plans from runs started with a run trigger. You can find this setting in the Settings page of your workspace.

Next steps

In this tutorial, you created a new workspace that uses the tfe_outputs data source to share information between workspaces. Then, you configured a run trigger so that when you make changes in your source repository, HCP Terraform starts a new run in your destination repository.

For more information on the tfe_outputs data source and run triggers, refer to the following resources:

• Read the tfe_outputs data source registry documentation
• Reference the run triggers HCP Terraform documentation.

Continue to the next tutorial to learn how to run other types of operations in HCP Terraform, such as refresh-only operations.