Terrafile Usage
The Terrafile is where you can define additional modules to add to your Terraspace project. The modules can be from your own git repositories, other git repositories, or the Terraform Registry.
You may also be interested in this blog post: Terraspace Terrafile: Using Git Repos and Terraform Registry Modules.
Example
Here’s an example Terrafile.
org "boltops-tools" # set default org
# Repo examples
mod "s3", source: "git@github.com:boltops-tools/terraform-aws-s3"
# mod "pet", source: "https://github.com/boltops-tools/random_pet" # public repo
# mod "elasticache", source: "boltopspro/terraform-aws-elasticache" # explicit org
# mod "redis", source: "terraform-aws-elasticache" # inferred org
# mod "bucket1", source: "terraform-aws-s3", version: "master" # pinned to branch. easily update with terraspace bundle update
# mod "bucket2", source: "terraform-aws-s3", tag: "v0.1.0" # pinned to tag no matter what
# mod "null_resource", source: "https://github.com/boltops-tools/modules", subfolder: "path/to/null_resource_module"
# Terraform registry
mod "sg", source: "terraform-aws-modules/security-group/aws", version: "3.10.0"
Options Docs:
- Mod-level options: : These options apply at the mod-level, so they specifically affect each mod only.
- Terrafile-level options: These options apply globally and affect the entire Terrafile.
Additional Docs:
- Version Locking Docs: Everything you may want to know about version locking.
- Stack Options: The
stackoption tells Terraspace to copy examples from modules to theapp/stacksfolder. There are a variety of ways to use it.
Install
When you run:
terraspace bundle
The modules in Terrafile are downloaded to the vendor/modules folder.
A Terrafile.lock file is generated to lock module versions. You can then check in the lockfile into version control. Other members on your team running terraspace bundle will download the exact same versions as you.
Usage
Here’s a demo stack that uses the downloaded vendor/modules/s3 module.
app/stack/demo/main.tf
resource "random_pet" "this" {
length = 2
}
module "bucket" {
source = "../../modules/s3" # looks up either app/modules/s3 or vendor/modules/s3
bucket = "bucket-${random_pet.this.id}"
acl = var.acl
}
A module downloaded to vendor/modules/s3 is sourced same way as if they were defined in app/modules/s3. This is because Terraspace considers multiple lookup paths. Docs: Lookup Paths
Here’s an example repo based on these docs: boltops-tools/terraspace-demo-terrafile
Terrafile.lock
A Terrafile.lock file is also generated. This file can be committed to version control to ensure that everyone on the team uses the exact same version.
Updating
To update the Terrafile.lock with the latest versions.
terraspace bundle update
You can also selectively update multiple modules.
terraspace bundle update mod1 mod2
Listing
You can list the modules that installed from the Terrafile with:
$ terraspace bundle list
Modules included by Terrafile.lock
ec2
rds
vpc
Use `terraspace bundle info` to print more detailed information about a module
Getting Info
You can get additional information about each bundled module with:
$ terraspace bundle info vpc
vpc:
sha: 30df090adc9d1a0d396551fd51ce11e780065b76
source: terraform-aws-modules/vpc/aws
stack: "examples/simple-vpc"
type: registry
url: https://github.com/terraform-aws-modules/terraform-aws-vpc
$
Stack Option
Often modules come with examples. Terraspace can copy these starter examples to the app/stacks folder for you. Terraspace also will rewrite the module source attribute to point to the correct location. This streamlines the terraspace bundle workflow. Example:
mod "vpc", source: "terraform-aws-modules/vpc/aws", stack: "simple-vpc"
Terraspace copies vendor/modules/vpc/examples/simple-vpc to app/stacks/vpc. For most examples, you’ll be able to deploy immediately:
terraspace up vpc
More Docs: Stack Options
