Trigger HCP Terraform runs from VCS changes

A workspace in HCP Terraform represents your Terraform configuration, a single state file, and your variable values. When you perform a Terraform operation, the HCP Terraform runs the Terraform operation and reports the progress. You can configure your workspace to use one of the following workflows:

• VCS-driven workflow: HCP Terraform fetches your configuration from your version control repository and automatically starts plan and apply operations whenever you make changes to the repository. This keeps your repository as the single source of truth for the workspace.
• CLI-driven workflow: Use your local Terraform CLI to start remote operations in HCP Terraform. HCP Terraform runs the operation and manages the state file.
• API-driven workflow: Use the HCP Terraform API to upload Terraform configuration changes and manage Terraform operations.

To use the VCS-driven workflow, you must configure a VCS connection in HCP Terraform and associate a workspace with the repository containing your Terraform configuration. You can then configure your workspace to create speculative plans for any pull requests, which allows your team to review how the changes would modify infrastructure. Any merges to your main branch then trigger Terraform runs to implement your changes.

In this tutorial, you will configure GitHub as a VCS provider so that you can connect workspaces to repositories in your GitHub account. Then, you will create a new VCS repository and a VCS-driven workspace. After you apply the configuration, you will also create a new pull request to see how you can use speculative plans to do code reviews.

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 AWS resources including an EC2 instance, VPC, and security groups.
• A GitHub account.

Configure VCS provider

To create VCS-driven workspaces, you must connect HCP Terraform to your VCS provider. This tutorial uses GitHub, but HCP Terraform supports many other VCS providers. Refer to Connect to VCS providers for a full list of supported providers.

To connect your HCP Terraform organization to your GitHub account, navigate to your organization's Settings page, then under the Version Control section, click Providers.

On the next screen, click Add a VCS provider button. Click the GitHub drop-down and choose GitHub.com (Custom).

Follow the steps shown on the Set up provider page to register a new OAuth application with your GitHub account. These steps tell you how to create a new OAuth application in GitHub, retrieve the client ID and secret, and configure them in HCP Terraform.

Once you set the values, click Connect and continue.

HCP Terraform redirects you to GitHub to authorize the new connection. Click Authorize to complete the connection.

Finally, HCP Terraform shows the Advanced Settings page. You can use these settings to limit which projects have access to this VCS provider, specify how organization members can use this provider, and configure a private SSH key. For this tutorial, keep the default settings and click Skip and finish to complete the VCS provider configuration.

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. Click Create repository to create your own copy of the repository.

This repository contains the following files:

• terraform.tf: Configures Terraform and the AWS provider.
• main.tf: Defines one AWS EC2 instance.
• variables.tf: Defines two variables named instance_name and instance_type, both with default values.
• outputs.tf: Defines one output named instance_hostname.

Create VCS-driven workspace

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

From the VCS-providers overview page in HCP Terraform, click Workspaces to navigate to the workspaces overview page. In the top-right corner, click the New drop-down and choose Workspace. Select the Default Project and click Create.

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

So far, you have created a workspace attached to your VCS repository that contains the Terraform configuration but you have not yet started a Terraform run or created infrastructure. Before you start a Terraform operation, review the workspace and the options you have to configure it.

Click Go to workspace overview to review the workspace you just created.

On the workspace overview page, HCP Terraform shows information such as the VCS repository it is connected to, the resources it manages, and the outputs from the most recent successful run.

Configure workspace variables

You can set values for the variables defined in your Terraform configuration in your HCP Terraform workspace. The configuration for this workspace defines two variables, instance_name and instance_type:

variable "instance_name" {
  description = "Value of the EC2 instance's Name tag."
  type        = string
  default     = "learn-terraform"
}

variable "instance_type" {
  description = "The EC2 instance's type."
  type        = string
  default     = "t2.micro"
}

To override the default value of the instance_name variable, create a workspace variable with the same name in your HCP Terraform workspace.

From your workspace overview page, click Variables in the left navigation menu. Next, click the Add variable button.

This interface lets you set both Terraform input variables and environment variables for the remote environment Terraform will run in. For this variable, select Terraform variable.

In the variable Key field, enter instance_name. For the Value, enter learn-hcp-terraform.

If a variable contains sensitive information, you can mark it as sensitive to make it write-only and prevent HCP Terraform from showing it in the user interface. You can also provide a description to give more information about the variable.

Click Add variable to finish creating the variable.

Workspace variables in HCP Terraform override the default values defined in your configuration.

Configure AWS authentication

Before you can start a Terraform operation, you must provide your cloud provider credentials to the workspace. Terraform providers define how you provide your authentication information. One way to authenticate the AWS provider is to set the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables with your AWS key and secret.

Click Add variable to create a new variable, but this time choose to create an Environment variables. Create the following variables:

Notice that since you marked the AWS_SECRET_ACCESS_KEY variable as sensitive, HCP Terraform does not show the value of the variable and the value is write-only.

Apply the configuration

Now that you created workspace variables to authenticate with AWS, you can start a Terraform plan and apply operation. Return to your workspace overview page and click New run. Ensure the Run type is set to Plan and apply (standard), then click Start.

After starting the run, HCP Terraform directs you to the run overview page. As your run progresses, HCP Terraform automatically updates this page with the details from the plan and apply operations. Once HCP Terraform completes the plan, it lists the resources to create, update, and delete.

HCP Terraform pauses the operation and waits for you to verify the changes. In this example, your Terraform configuration creates one new aws_instance. Click Confirm & apply, then click Confirm plan to resume the run.

Once HCP Terraform completes the run, it shows you the new aws_instance resource it created, along with the outputs defined in your configuration.

Click Overview in the left navigation panel to return to the workspace overview page.

Your workspace now contains information about the latest run, the resources and data sources that the workspace manages, and the outputs from the most recent run. The overview also shows information about the version of Terraform you configured the workspace to use, and it has a link to the VCS repository you used to create the workspace.

Update configuration

Your workspace tracks changes to your VCS repository. By default, HCP Terraform starts a new plan-only operation when you make a commit to a pull request, and starts an apply operation any time a new commit is made to the default branch in your repository.

Open your GitHub repository in your browser and open the outputs.tf file. Click the pencil icon in the top-right corner to edit the file, and add a new output named instance_ami with the following configuration:

output "instance_hostname" {
  description = "Private DNS name of the EC2 instance."
  value       = aws_instance.app_server.private_dns
}

output "instance_security_group_ids" {
  value = aws_instance.app_server.vpc_security_group_ids
}

output "instance_subnet" {
  value = aws_instance.app_server.subnet_id
}

+ output "instance_ami" {
+   description = "AMI used to create the EC2 instance."
+   value       = aws_instance.app_server.ami
+ }

Click Commit changes. When prompted, choose Create a new branch for this commit and start a pull request. Name the branch add-ami-output, then click Propose changes. GitHub then shows you the Open a pull request page that summarizes the changes to merge into main. Click Create pull request to open the pull request.

By default, when you open a new pull request in a repository attached to a VCS-driven workspace, HCP Terraform runs a speculative plan operation. Speculative plans run without waiting for other workspace operations to complete. Additionally, they only run the Terraform plan operation. You cannot use them to perform a Terraform apply. Speculative plans are useful for proposing changes and waiting until the final merge to actually deploy them.

After a few moments, notice that HCP Terraform added a new check to your GitHub pull request. This action links to the speculative plan in HCP Terraform and passes the check if the Terraform plan was successful. Click Merge pull request to complete the changes.

Return to your HCP Terraform workspace and click Runs in the left navigation panel. HCP Terraform creates another new run now that you merged your pull request, this time as a plan and apply operation. Click the run to view the details.

Wait for the plan to complete, click Confirm & apply, then click Confirm plan to complete the operation.

When the operations completes, return to your workspace overview page, click the Outputs tab, and notice that it lists the new instance_ami output.

Next steps

In this tutorial, you created a VCS repository with your Terraform configuration, then used it to create a new VCS-driven workspace. Then, you created Terraform and environment variables to customize the run and authenticate to AWS. You then updated your code and used HCP Terraform to automatically apply those changes.

For more information on HCP Terraform variable precedence, refer to the Workspace variables in HCP Terraform documentation.

Continue to the next tutorial to learn how to use projects and variable sets to manage multiple workspaces.