Effectively Using a VCS with Terraform Enterprise

This is the third guided tutorial for HashiCorp Terraform Enterprise (TFE). In this tutorial a user will be integrating and optimizing their use of a version control system with Terraform Enterprise.

This demonstration will enable a user—typically an operator—to understand how a version control system (VCS) integrates with HashiCorp Terraform Enterprise (TFE). We'll cover: 1. automatically executing plans after commiting code, 2. utilizing different branches for workspaces, and 3. how actions such as pull requests can take advantage of the tight integration between TFE and a VCS.

After completing this tutorial, you'll be able to use a VCS to effectively manage multiple environments from the same VCS repository, and be able to demonstrate team collaboration workflows.

Terraform uses an infrastructure as code approach to provide effective, reusable, safe infrastructure-provisioning automation. This approach enables operators to increase their productivity, move quicker, and reduce human error.

A common pattern of use with Terraform Enterprise is to use VCS branches for testing changes, prior to merging them into the master branch.

For planning purposes, we expect the steps in this guide to take no more than 20 minutes. Where applicable, links to code have been provided.


Pre-Configured Environment:

There is already a workspace created in the Getting Started with Terraform Enterprise Guide, for the application referencing the master branch:

These are the current configured variables:

Create a New Workspace for Branch Testing

Create a new Workspace for testing. This workspace will reference the same repository and folder structure as your current application.

New Workspace:

Workspace configuration:

<em>Note: We are intentionally skipping setting the new branch name in this step.</em>
Note: We are intentionally skipping setting the new branch name in this step.

Set your variables to make this environment unique. In this example, we are referencing the same network workspace, but will be making the application space unique.

Change these variables to be:

Save and run your Plan:

Apply your plan:

Setup a New VCS Branch

In the repo we referenced above, create a new branch:

In TFE, navigate to the Version Control settings:

Modify the Branch settings and Update VCS settings:

After updating the settings, a plan will automatically be run against the new branch. Since the branch matches the master at this point, no changes are detected, and Apply does not need to be run.

Finally, turn on Auto-Apply for your Terraform workspace (this is an optional step, but for test environments, it can help on iterating through changes much more quickly).

If the plan passes and doesn't fail, Terraform Enterprise will automatically kick off the Apply of the change as well.

Modify your Terraform Configuration

Using the branch you just created and setup, modify the configuration you want to make changes to.

In this example, we're adding an additional disk to the server configuration:

Commit your changes to the test branch:

Once the changes are committed, a plan is automatically kicked off in Terraform Enterprise:

Because we turned on auto-apply earlier, the plan is automatically run:

Both the Plan and Apply output can be viewed to see what was planned to be changed, and what actually occurred. You can view this under Current Run.

Run a Pull Request

Terraform Enterprise has a tight integration with your VCS, and automatically testing pull requests is a feature that can be very helpful.

At this point, we’ve been able to test the code directly in our test branch, and it is time to merge the two branches.

Open a Pull Request:

Here we can see that all branches that are part of this pull request are tested. In this example, two environments have no changes, but the main application tied to the master branch has changes.

Click on Details to view the changes that are going to occur.

We can also view the plan and see that it was successful:

It's not possible to apply the plan at this point. This is only a record of the plan. Once the code is committed into the master branch, the apply can be executed.

Merge the Test Branch

At this point, we've verified that the plans have run successfully. We were able to click into the details to verify what changes are planned to occur, and now we can successfully merge the pull request.

Confirm that you want to merge this pull request:

In Terraform Enterprise, we can see that, because a merge occurred, plans have kicked off for the two workspaces linked to the master branch:

At this point, since we don't have auto-apply turned on for the workspace pointed to the master branch, we can click in to view the details and apply the changes:

After the we apply the changes, we can see how the environment looks:

Destroy Test Environment

A big benefit of Terraform is that it knows about all of the resources that were required to build your test space—so it can successfully tear down all the components that are not longer needed. Since it's so easy to recreate the environment, we should tear it down when it isn’t in use.

Open the test workspace and navigate to settings:

Scroll to the bottom to queue a destroy of the environment.

Note: You must have the environment variable 
 set to 1 to have the 
<em>Queue destroy Plan</em>
 button clickable.
Note: You must have the environment variable CONFIRM_DESTROY set to 1 to have the Queue destroy Plan button clickable.

Click the Queue Destroy Plan button to kick off a plan for destroying the in-use resources.

At this point, we can see the plan has run:

We can now apply it:

Once the apply is complete, the workspace is empty and ready for future tests.

Next Steps

You have now successfully: - incorporated your VCS into Terraform Enterprise, - walked through the process of using different workspaces to test different branches of code, and - seen how Terraform can automatically apply changes to your infrastructure as you open and merge pull requests in your VCS.

Now continue to use these best practices with your VCS as you build with Terraform Enterprise.

More resources like this one

  • 3/15/2023
  • Presentation

Advanced Terraform techniques

  • 2/3/2023
  • Case Study

Automating Multi-Cloud, Multi-Region Vault for Teams and Landing Zones

  • 2/1/2023
  • Case Study

Should My Team Really Need to Know Terraform?

  • 1/20/2023
  • Case Study

Packaging security in Terraform modules