Please review the official terragrunt readme to find more details on how to use terragrunt. It is very long so to highlight the important parts, read on.

Structure

There are two terragrunt.hcl files needed to make a terragrunt deployment work.

1. The root terragrunt.hcl file at the root of the main repo
2. The module level terragrunt.hcl file that actually deploys the terraform modules

Remote State

Both files are needed as the relative path between these two files ends up being persisted in S3 as the path to the state. Thus if your folder structure looks like this

├── terragrunt.hcl
├── icon
│   ├── bastion
│   │   ├── ec2
│   │   │   ├── aws_provider.tf
│   │   │   └── terragrunt.hcl
│   │   ├── sg
│   │   │   ├── aws_provider.tf
│   │   │   └── terragrunt.hcl

then the remote state in s3 would look

├── icon
│   ├── bastion
│   │   ├── ec2
│   │   │   └── terraform.json 
│   │   ├── sg
│   │   │   └── terraform.json 

Organizing the remote state to persist it in a remote location is one of the biggest selling points for terragrunt.

Syntax

Here is a little overview of the syntax and how we use it at Insight

Root Level Terragrunt

At the base of the repo, there is a terragrunt.hcl file that looks like this: