Scaffold

Scaffold

Terragrunt scaffolding can generate files for you automatically using boilerplate templates.

Currently, one boilerplate template is supported out-of-the-box, which you can use to generate a best-practices terragrunt.hcl that configures a Terraform module for deployment:

terragrunt scaffold <MODULE_URL> [TEMPLATE_URL] [--var] [--var-file]

Description:

• MODULE_URL - URL to a Terraform module. Can be a local file path, git URL, registry URL, or any other module source URL.
• TEMPLATE_URL - Optional URL to a custom boilerplate template to use to generate HCL files. Can be a local file path, git URL, registry URL, or any other module source URL. If not specified, Terragrunt will:
  • Look for a .boilerplate folder in the module at MODULE_URL, and if found, use the boilerplate template in that folder.
  • Failing to find that, Terragrunt will use a boilerplate template that is built-in, which creates a best-practices terragrunt.hcl for deploying a single Terraform module.

For example, here’s how you can generate a terragrunt.hcl file to configure an example MySQL Terraform module for deployment:

terragrunt scaffold github.com/gruntwork-io/terragrunt-infrastructure-modules-example//modules/mysql

This will create a terragrunt.hcl in your current working directory, with roughly the following contents:

# This is a Terragrunt module generated by boilerplate.
terraform {
  source = "git::https://github.com/gruntwork-io/terragrunt-infrastructure-modules-example.git//modules/mysql?ref=v0.8.1"
}

inputs = {
  # --------------------------------------------------------------------------------------------------------------------
  # Required input variables
  # --------------------------------------------------------------------------------------------------------------------

  # Type: string
  # Description: The AWS region to deploy to (e.g. us-east-1)
  aws_region = "" # TODO: fill in value

  # Type: string
  # Description: The name of the DB
  name = "" # TODO: fill in value

  # Type: string
  # Description: The instance class of the DB (e.g. db.t2.micro)
  instance_class = "" # TODO: fill in value

  # (... full list of inputs omitted for brevity ...)
}

Important notes:

• The source URL is configured for you automatically, with the ref pointing to the latest “release” tag of the module (found by scanning git tags).
• The inputs section is generated for you automatically, and will list all required and optional variables from the module, with their types, descriptions, and defaults, so you can easily fill them in to configure the module as you like.

Custom templates for scaffolding

Terragrunt has a basic template built-in for rendering terragrunt.hcl files, but you can provide your own templates to customize what code is generated! Scaffolding is done via boilerplate, and Terragrunt allows you to specify custom boilerplate templates via two mechanisms:

1. You can specify a custom boilerplate template to use as the second argument of the scaffold command.
2. You can define a custom boilerplate template in a .boilerplate subfolder of your module.

If you define input variables in your boilerplate template, Terragrunt will prompt users for the values. Those values can also be passed in via --var and --var-file arguments. There are also a set of variables that Terragrunt will automatically expose to your boilerplate templates for rendering:

• sourceUrl - URL to module
• requiredVariables - list of required variables in the module being scaffolded (see below)
• optionalVariables - list of optional variables in the module being scaffolded (see below)

The elements in the requiredVariables and optionalVariables lists are structs with the following fields:

• Name - variable name
• Description - variable description
• Type - variable type (string, number, bool, list, map, object) Type Constants
• DefaultValue - variable default value
• DefaultValuePlaceholder - default value placeholder, string = “”, number = 0 etc.

Optional variables which can be passed to scaffold command:

• Ref - git tag or branch name for module to be used
• EnableRootInclude - add in default terragrunt.hcl inclusion for the root module, by default true
• SourceUrlType - if set to git-ssh module url will be converted to Git/SSH format
• SourceGitSshUser - git user for Git/SSH format, by default git

Examples

Scaffold new project but use specific module version:

terragrunt scaffold github.com/gruntwork-io/terragrunt.git//test/fixture-inputs --var=Ref=v0.53.1

Scaffold new project but use Git/SSH URLs:

terragrunt scaffold github.com/gruntwork-io/terragrunt.git//test/fixture-inputs --var=SourceUrlType=git-ssh

# terragrunt.hcl
terraform {
  source = "git::ssh://git@github.com/gruntwork-io/terragrunt.git//test/fixture-inputs?ref=v0.53.8"
}

Scaffold new project using template inside of git repo:

terragrunt scaffold github.com/gruntwork-io/terragrunt.git//test/fixture-scaffold/module-with-template
# will be used template from .boilerplate directory to generate terragrunt.hcl

Scaffold new project using external template:

terragrunt scaffold github.com/gruntwork-io/terragrunt.git//test/fixture-inputs git@github.com/gruntwork-io/terragrunt.git//test/fixture-scaffold/external-template

# will be created: external-template.txt terragrunt.hcl , files from external template