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:
Replace <your-fast-foundation-repo-url> with the actual repository URL provided by your team.
2

Configure Provider Plugin Cache (required)

Fast Foundation modules are sourced from a dedicated git repository. Each terragrunt init clones the modules and downloads provider plugins. Without caching, the AWS provider alone (~762MB) gets duplicated in every unit’s .terraform/ directory — with 40+ units this adds up to tens of gigabytes of wasted disk space.The provider plugin cache stores provider binaries once and hardlinks them into each unit, reducing per-unit storage overhead to effectively zero.More information can be found in the official terraform documentation.Step 1: Create the cache directory:
Step 2: Create or edit ~/.terraformrc with these two lines:
Both lines are required. Without plugin_cache_may_break_dependency_lock_file, Terraform copies provider binaries instead of hardlinking them, negating the disk savings.
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:
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:
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:
5

Apply changes

Apply the configuration:
Your infrastructure changes have been applied successfully.

​
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 and deploy a custom wrapper module.