Skip to main content
AWS Single Sign-On (SSO) Required: This guide assumes your AWS Identity Center (formerly AWS SSO) is already configured. If not, complete the AWS SSO Setup guide first.

​
Repository Setup & Usage Example

1

Clone the Infrastructure Repository

Begin by cloning your organization’s Fast Foundation infrastructure repository:
git clone <your-fast-foundation-repo-url>
cd <fast-foundation-infrastructure-folder>
Replace <your-fast-foundation-repo-url> with the actual repository URL provided by your team.
2

Configure Provider Plugin Cache (optional, but strongly recommended)

By default, terraform init downloads plugins into a subdirectory of the working directory so that each working directory is self-contained. As a consequence, if you have multiple configurations that use the same provider then a separate copy of its plugin will be downloaded for each configuration.Given that provider plugins can be quite large (on the order of hundreds of megabytes), this default behavior can be inconvenient for those with slow or metered Internet connections. Therefore Terraform optionally allows the use of a local directory as a shared plugin cache, which then allows each distinct plugin binary to be downloaded only once.More information can be found in the official terraform documentation.To enable the plugin cache:
# Open the CLI configuration file
vi ~/.terraformrc

# Add this line to the file and save it
plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"
This directory must already exist before Terraform will cache plugins; Terraform will not create the directory itself. If it does not exist, create it running mkdir -p $HOME/.terraform.d/plugin-cache
3

Initialize Terragrunt

If you have admin permissions to the entire organization, you can initialize the entire repository from the root directory. If not, run this from an account or region folder. Initialize Terragrunt:
terragrunt run --all init --provider-cache
The initialization process can take some minutes to finish.
What happens here:
  • Terragrunt initializes the backend for all the units.
Expected output:
  • For each unit that is initialized, you should see:
Terraform has been successfully initialized!

You may now begin working with Terragrunt. Try running "terragrunt plan" inside a terragrunt unit to see any changes that are required for your infrastructure. All Terraform commands should now work.
If you ever set or change modules or backend configuration for Terragrunt, run this command again to reinitialize your working directory. If you forget, other commands will detect it and remind you to do so if necessary.
4

Plan before applying changes

Review planned infrastructure changes. Move into the workload-core-development account directory, we will use the clusters VPC as an example:
cd Workloads/Development/workload-core-development/development/<region>/networking/vpc/clusters
terragrunt plan
5

Apply changes

Apply the configuration to deploy the organization structure:
terragrunt apply
Your organization and member accounts are now created.

​
Troubleshooting

Symptoms: Access Denied errors during Terragrunt operations.Possible causes:
  • SSO (AWS IAM Identity Center) session expired.
  • Misconfigured AWS profile.
  • Missing IAM permissions.
Solutions:
  1. Verify your session: aws sso login --sso-session fast-foundation
  2. Check your profile in ~/.aws/config
  3. Ensure your user/role has the required IAM permissions.

​
State lock issues

Terragrunt and Terraform use DynamoDB locks to prevent multiple people from applying changes at the same time on the same unit. If you see a state lock error, it usually means someone else is already running a deployment.What to do:
  • ⏳ Wait for the other deployment to finish.
  • ✅ Verify you’re not overwriting someone else’s changes.
  • 🚀 Apply your changes once you’re sure everything is okay.
Symptoms: Terraform module cannot be downloaded or located.Solutions:
  1. Run terragrunt init again to refresh modules.
  2. Check internet connectivity for module downloads.
  3. Verify module source paths in configuration files.

​
Want to dive deeper?

Ready to explore these concepts in more detail? Check out our hands-on workshops:

Deploy an EC2 instance

Learn step-by-step how to create an EC2 instance with external modules.

Deploy a custom module

Learn step-by-step how to create an EC2 instance with external modules.