Managing Terraform infra in Cortex

Terraform is an infrastructure-as-code tool 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. Providers allow you to define as code what a resource looks like.

The instructions on this page apply to Terraform Cloud, the web-based interface for Terraform.

How to manage Terraform infrastructure in Cortex

Before getting started

• Provision a new instance

  • Terraform will automatically provide you with a starter workspace when you begin — our example workspace is named "tfc-guide-example".

Our example workspace is named "tfc-guide-example"

• Update the instance name in the Terraform variables.tf file.

  • 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. In the example screen shot below, the variable name is "My Other Great Instance".

The variable instance name is "My other great instance."

• Note: 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.

Example of the main.tf file

Terraform stores a “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.

Step 1: Confirm your instance name update in Terraform

In Terraform Cloud, navigate to the Run page. Verify that the changes you made to the instance name in variables.tf have applied.

In Terraform, verify that your changes have applied.

In Terraform, there are two primary commands: plan and apply.

• The plan command 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 you navigate to the run that was triggered by updating variables.tf, you can see that the plan was automatically conducted. In this case, the plan was to create an instance with the name provided earlier. Verify that the run displays a "Plan finished" message.

Terraform displays a "Plan finished" message.

In AWS, you can confirm that the instance exists and that the Terraform action was successful:

AWS shows that the instance exists.

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

Step 2: Add the Terraform template in Cortex

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

You must have the Configure Scaffolder templates permission.

When using the Scaffolder, it's 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.

1. Create a Cookiecutter JSON file that is equivalent to your 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.
2. Register your template in Cortex.
3. After you have added the template to Cortex, you can create a Workflow that includes a Scaffolder block using the template.
4. Run the Workflow. When you run it, Cortex will automatically open a pull request against the selected repository.

Verify that the process worked

To verify that the process worked, open Terraform Cloud and navigate to Runs.

Any runs that originate from Cortex will have [Cortex Scaffolder] at the start of their name. Click into one of these runs to see its status and how many changes were proposed.

A Cortex Scaffolder run shows as planned and finished in Terraform.

Execute a run via a Workflow

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

1. Create a Workflow in Cortex.

2. Add a user input block.

   1. Define inputs for Instance name, Region, and Instance type.

3. Add an HTTP request block. Configure the following fields:

   1. HTTP method: Select POST.

   2. URL: Enter the URL for the Terraform API you want to call.

   3. Headers: Add Authorization: Bearer {{token}} and Content-type: application/(name).

   4. Payload: Build the payload by referencing the outputs of the "User input" block, e.g., {{actions.input.outputs.instance-name}}

4. Save the Workflow. After saving, click Run at the top of the Workflow to run it.

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

Verify the run

In Terraform Cloud, you can verify that the action was successful and the run was queued. Runs triggered by actions are named "Triggered via API."

The run in Terraform is labeled "Triggered via API."

Once the run has been applied, you can also verify it in AWS. In the example screen shot below, the instance name has been changed:

The instance is listed in AWS.