Terraform is an infrastructure-as-code tool created by HashiCorp that lets you provision, manage, and update infrastructure. Terraform can help you manage databases, s3 buckets, clusters, and every other component that comprises your infra. 

Terraform’s ability to manage resources comes from providers, which are plugins that enable interaction with cloud providers, SaaS providers, and other APIs. Essentially, providers allow you to define as code what a resource looks like.

In this article, we’ll be looking specifically at Terraform Cloud, the web-based interface for Terraform. 

Getting started with Terraform

Terraform will automatically provide you with a starter workspace when you begin — our sample workspace is named tfc-guide. While Terraform has a lot of useful functions, for our purposes we’ll start with provisioning a new instance.

All Terraform modules come with a file called variables.tf. As part of the Terraform script, we can enter variables for a given set, like region or instance type. For now, let’s change the instance name.

Terraform modules also come with a main.tf file, which contains instructions and information about the action. In our example, the main.tf file describes the instance that we’re going to create through Terraform.

Terraform will store “state” about your infrastructure and configuration when it’s deployed. State maps resources to this configuration, and will update any time variables or properties are changed.

When we go back to Terraform Cloud and navigate to the Run page, we can see that the changes we made to the instance name in variables.tf are applying.

In Terraform, there are two primary commands: plan and apply. The plan command does exactly that — it creates a plan and preview of the changes that will be made to your infrastructure. During the plan stage, Terraform assesses the main.tf file with variables and compares it against the state. If there are differences, Terraform prompts you to approve and apply the change.

When we navigate to the specific run we just triggered, we can see that the plan was automatically conducted. In this case, the plan was to create an instance with the name provided earlier. Below that, we can see that the apply was finished.

In AWS, we can confirm that the instance exists and that our Terraform action was successful. 

In this example, we made direct modifications to the main branch, but typically, users will edit a separate branch and create a pull request. This approach will run a plan in Terraform, but will not automatically apply changes.

We’ll take a look at how that method works in the next section when we review how to integrate Terraform and Cortex.

Using Terraform in Cortex

Cortex not only integrates with Terraform, but can enhance your use of it. Once the integration is set up, you’ll use the Scaffolder and Actions to interact with Terraform.

Scaffolder

When using the Scaffolder, it works best to edit a secondary branch and create a pull request — the Scaffolder will actually create the pull request for you, which someone else can approve to apply the changes.

Because the Scaffolder uses Cookiecutter to create and add to templates, our first step is to create a Cookiecutter JSON file that’s equivalent to our Terraform module. 

In this file, we defined the region and instance name.  You’ll then update the fields in the variables.tf file so it knows to pull information from the Cookiecutter JSON.  

In Cortex, when we use the corresponding Scaffolder template to create an instance, we’ll see the same fields appear.

We named our instance myScaffolderInstance and set the region to us-east-2 (one of the regions defined in the JSON file above) — these are the same variables we defined in the variables.tf file. The Project Slug field is required for all Cookiecutter templates; this won’t impact your Terraform action.

In the Configure repository section, we selected tfc-guide-example, the module that we’ve been working with. You’ll also be asked to provide a Branch to create at this stage.  

When you click Run Scaffolder, Cortex will automatically perform a pull request against the selected repository.

We can confirm that this worked by navigating back to Runs in Terraform Cloud. 

Any runs that originate from Cortex will have [Cortex Scaffolder] at the start of its name. When we navigate into this run, we can see that it was Planned and finished, but not yet applied, and we can see how many changes were proposed.

Actions

Terraform Cloud also has an API that can be used to make updates without following the pull request workflow. You can use Actions in Cortex to execute a run through the API. If a run is set to automatically apply, then Cortex will handle every step of the process for you.

For this example, we’ve created an action called Provision EC2 Instance (Terraform Cloud). 

The action is set with three Action inputs, information that users are required to enter when triggering the action: Instance Name, Region, and Instance Type. These are the same data that we required when creating the Cookiecutter JSON file.

 Under Action definition, you’ll input the URL for the Terraform API you want to call, as well as a Bearer token and application type. In Payload JSON, you can pass variables to the run.

When an action is triggered in Cortex, it will override data in the variables.tf file with information that was entered in the fields. 

To run the action, we’ll select Run Action from the Provision EC2 Instance page. Note that from this page, we can also view the action’s configuration and the inputs it requires.

Clicking Run Action will open a modal window where we can enter the Instance Name and select the Region and Instance Type from the dropdowns.  

When we go back to Terraform Cloud, we can see that the action was successful, and the run was queued. Runs triggered by actions will be named Triggered via API. 

Once the run has been applied, we can confirm that it worked in AWS.

As we can see, the instance has successfully been renamed