Effectively Using a VCS 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.

• You've already gone through Getting Started with Terraform Enterprise, to connect your VCS to Terraform Enterprise, as well as set up user accounts.
• You've created or have access to an existing public VCS repo from the supported list, available at Connecting VCS Providers to Terraform Enterprise
• You've created a module with the identified requirements or cloned one of the examples

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 testing. This workspace will reference the same repository and folder structure as your current application.

New Workspace:

Workspace configuration:

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:

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.

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.

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.

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:

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.

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.

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.