Skip to main content

​
Step-by-Step Process

​
1. Navigate to the Correct Directory

Move into the appropriate environment directory: For development: 
cd Workloads/Development/<workload-development>/development/<region>/cluster-permissions/applications/config
For production: 
cd Workloads/Production/<workload-production>/production/<region>/cluster-permissions/applications/config

​
2. Initialize Terraform

terragrunt init
This command will:
  • Initialize Terraform
  • Download the inputs.hcl files from S3 with your existing configurations, or create a new one.

​
3. Configure Your Application

Edit the inuts.hcl file and add your service definition under the microservice section. 
{
  name = "your-app-name"
  tier = "application"
  ecr  = {}
  
  deployer = {
    additional_policy_statements = {}
    allowed_ssm_parameter_arns   = []
    
    oidc = {
      audiences = [
        "sts.amazonaws.com"
      ]
      subjects_with_wildcards = []
      subjects = [
        "repo:your-org/your-app:ref:refs/heads/development",
        "repo:your-org/your-app:environment:development"
      ]
    }
  }
  
  static_secret = {
    create             = true
    additional_secrets = []
  }
  
  clusters = {
    "dev-1-31-your-cluster" = {
      create_secret                            = false
      additional_secrets                       = []
      application_additional_policy_statements = {}
    }
  }
}

​
Configuration Fields Explained

FieldDescriptionExample Value
nameUnique application name"your-app-name"
tierApplication tier (usually "application")"application"
namespaceEnvironment namespace"development" or "production"
ecrECR (Elastic Container Registry) settings{} (empty for default)
deployer.oidc.subjectsGitHub repository + branch patterns"repo:your-org/your-app:ref:refs/heads/branch-name"
static_secret.createCreate environment variables secret?true
clustersPer-cluster configurationDefines secrets and IAM policies
  • Use a unique name for each application to avoid conflicts
  • Update the subjects array with your actual GitHub repo and branch names
  • Replace your-org/your-app with your GitHub organization and repository
  • Update the cluster name to match your target cluster
When you save the configuration, Fast Foundation automatically creates the following AWS resources:

Pipeline Role

IAM role for your CI/CD pipeline to deploy the application

Application Role

IAM role for your app to access AWS services

Application Secret

AWS Secrets Manager secret for environment variables

ECR Repository

Container registry for storing Docker images

​
4. Plan and Apply Changes

Run the following commands to review and apply changes: 
# Review what will be created
terragrunt plan

# Apply changes (save to parameter store)
TG_SECRET=save terragrunt apply
The TG_SECRET=save flag ensures your local configuration is persisted to AWS.

​
5. Save the Output Values

After Terraform applies successfully, capture the output values: 
terragrunt output

​
Example Output

A typical output looks like this: 
"app_name" = {
  "cluster_resources_per_cluster" = {
    "cluster_name" = {
      "service_account_role_arn" = "arn:aws:iam::123456789101:role/cluster_name_environment_app_prefix"
    }
  }
  "ecr_repository" = "1110987654321.dkr.ecr.us-east-1.amazonaws.com/development/application/app_name"
  "pipeline_role" = "arn:aws:iam::1110987654321:role/deployer_environment_app_name"
  "static_secret" = "arn:aws:secretsmanager:us-east-1:123456789101:secret:environment/app_name/env-cDkfzs"
}

​
Understanding the Output Values

ValueDescriptionPurpose
service_account_role_arnRole used by Kubernetes service accountApplication permissions in cluster
ecr_repositoryContainer registry URLStores Docker images for the app
pipeline_roleCI/CD deployment roleUsed by GitHub Actions
static_secretARN of environment secretHolds app configuration variables

​
Configure Application Secrets

At this stage you can add your environment variables:
  1. Open AWS Secrets Manager in the AWS Console
  2. Find the secret created for your app
  3. Add key-value pairs for environment variables

​
Next Steps

With AWS resources created and outputs saved, move on to Create Manifest Files to configure your Kubernetes deployment.

​
Troubleshooting

Ensure you’re using AWS credentials with the right permissions for the workload account.

​
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.
Double-check you are in the correct directory and have successfully run tg init.