Note: Premium video content requires a subscription.

Terraspace makes it easy to use Terraform modules sourced from your own git repositories, other git repositories, or the Terraform Registry. The git repos can be private or public. This is an incredibly powerful feature of Terraspace because it opens up a world of modules for you. Use any module from anywhere.

Terraform Modules

First, let’s cover how external modules are typically added with Terraform. You use the module source code keyword. The code looks like this:

module "consul" {
  source = "hashicorp/consul/aws"
  version = "0.1.0"
}

module "example" {
  source = "github.com/hashicorp/example"
  version = "0.2.0"
}

Since Terraspace uses standard HCL, you can use the same approach to include modules. However, Terraspace offers an additional way to use external modules, and it comes with some extra benefits.

Terrafile Intro

With Terraspace, you can also add modules to your project with a Terrafile. Here’s an example that demonstrates modules both from:

1. GitHub repo
2. Terraform Registry

mod "s3", source: "boltops-tools/terraform-aws-s3"          # github repo
mod "ec2", source: "terraform-aws-modules/ec2-instance/aws" # terraform registry

When you run:

terraspace bundle

Terraspace downloads modules in the Terrafile to the vendor/modules folder.

Terraspace Docs: Terrafile

How vendor/modules Works

It’s worth explaining the vendor/modules and app/modules folders. You see, Terraspace is smart enough to source modules from either folder. For example, let’s say you have these modules:

app/modules/example
vendor/modules/s3
vendor/modules/ec2

Terraspace will source example from app/modules and s3 and ec2 from vendor/modules.

When terraspace up runs, it builds a Terraform project by copying the modules to the .terraspace-cache folder. This provides a transparent and smooth workflow experience with externally sourced modules.

Terraspace Docs: Lookups

Terrafile Advantages

The Terrafile advantages are centralization and automation. If you ever need to update the modules in the future, instead of jumping around multiple source files, finding all the module version lines, and manually editing them; you look in one spot: the Terrafile. To update the modules, it’s a single command:

terraspace bundle update

If you want to update select modules, you can specify their names:

terraspace bundle update mod1 mod2

A Terrafile.lock is generated. You commit this file into version control and share it with your team members. This ensures everyone uses the exact same version.

Additionally, since the source code version is downloaded to vendor/modules, it is easy to inspect the source code for debugging. You can even modify the files on the spot for quick edits and testing.

EC2 Instance Demo

Let’s walk through the steps with an EC2 instance from the Terraform Registry. Here’s a summary of the steps:

1. Add the module to Terrafile
2. Run terraspace bundle
3. Deploy stack

1. Add the module to Terrafile

First, start by generating a brand new Terraspace project:

terraspace new project demo
cd demo

Replace the starter Terrafile contents with the following:

Terrafile:

# terraform registry example
mod "ec2", source: "terraform-aws-modules/ec2-instance/aws", stack: "basic"

2. Run terraspace bundle

Next, run the bundle command:

$ terraspace bundle
Bundling with Terrafile...
Exporting ec2
Modules saved to vendor/modules

This downloads the modules to vendor/modules/ec2.

If you make changes to the Terrafile and need to update the modules later, you can use terraspace bundle update.

3. Deploy stack

In Terrafile, we used the stack: "basic" option. This option tells Terraspace to automatically copy the basic example from vendor/modules/examples/basic to app/stacks/ec2. This allows us to deploy examples immediately. Let’s list the generated stack:

$ terraspace list
app/stacks/ec2
$

The ec2 stack is available to deploy. Let’s deploy it:

$ terraspace up ec2
Building .terraspace-cache/us-west-2/dev/stacks/ec2
Built in .terraspace-cache/us-west-2/dev/stacks/ec2
Current directory: .terraspace-cache/us-west-2/dev/stacks/ec2
=> terraform apply
...
Apply complete! Resources: 12 added, 0 changed, 0 destroyed.
Time took: 58s
$

Note, the example ec2 stack deploys 4 instances to the eu-west-1 Ireland region:

Cleanup

Let’s clean up to save costs:

$ terraspace down ec2
Building .terraspace-cache/us-west-2/dev/stacks/ec2
Built in .terraspace-cache/us-west-2/dev/stacks/ec2
Current directory: .terraspace-cache/us-west-2/dev/stacks/ec2
=> terraform destroy
...
Destroy complete! Resources: 12 destroyed.
Time took: 1m 37s

We’ve destroyed the 4 test instances.

Summary

In this post, we covered how to use modules from git repositories and the Terraform registry. We introduced the Terraspace Terrafile concept. You can still use the traditional module source approach also. Terraspace allows you to use either or both approaches. It’s up to you. The Terrafile approach gives you the significant advantage of centralization and simplifies updating your modules to a single command. To learn more: Terraspace Terrafile Docs.