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 with Parameter Management

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.
  • Parameter management downloads S3 inputs.hcl files.
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.
If parameters differ between local and S3, you’ll see an error. Move to the directory that has the parameter drift and use TG_SECRETS=update (to pull S3 values) or TG_SECRETS=save (to overwrite with local values).
4

Plan with Drift Detection

Review planned infrastructure changes while validating parameters. 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
If parameter drift is detected:
[WARNING] Parameter drift detected between local and S3 versions.

Resolution options:
  → Use S3 version:   TG_SECRETS=update terragrunt plan
  → Use local version: TG_SECRETS=save terragrunt plan

⚠ Continuing with local parameters...
Parameter drift during terragrunt plan is a warning, but it must be resolved before running terragrunt apply.
5

Apply with Parameter Safety

Apply the configuration to deploy the organization structure:
terragrunt apply
On parameter drift, apply will block with an error:
[ERROR] Parameter drift detected between local and S3 versions.

Resolution options:
  → Use S3 version:   TG_SECRETS=update terragrunt apply
  → Use local version: TG_SECRETS=save terragrunt apply

Operation blocked due to parameter drift.
Resolve and retry:
# Sync with S3 first, then apply
TG_SECRETS=update terragrunt init
terragrunt apply
Your organization and member accounts are now created with synchronized parameters.

​
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.
  • ✅ Refresh your parameter. Save your current changes locally (they may be overwritten).
  • 🚀 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.