Skip to main content

Infrastructure Repository Migration

Reference documentation for the migration from a monolithic Terragrunt repository to the Gruntwork two-repository pattern.

Migration Status

Status: Complete
Date Completed: December 29, 2025
Version: v1.0.0

Overview​

This document describes the migration from a monolithic infrastructure repository to the Gruntwork two-repository pattern, which separates infrastructure modules from environment configurations.

What Changed​

Before: Monolithic Repository​

docustack-mono/
└── infrastructure/
    ├── modules/          # Local Terraform modules
    ├── dev/              # Dev environment configs
    ├── staging/          # Staging environment configs
    ├── prod/             # Prod environment configs
    └── management/       # Management account configs

Module References:

terraform {
  source = "${dirname(find_in_parent_folders("root.hcl"))}/modules/vpc"
}

After: Two-Repository Pattern​

Repository 1: docustack-infrastructure-modules (Catalog)

  • Reusable, versioned Terraform modules
  • Semantic versioning with Git tags
  • Independent module lifecycle

Repository 2: docustack-infrastructure-live (Live)

  • Environment-specific configurations
  • References modules via Git with version pinning
  • Terrateam stacks for dependency management

Module References:

terraform {
  source = "git::git@github.com:docustackapp/docustack-infrastructure-modules.git//modules/vpc?ref=v1.0.0"
}

Why This Pattern?​

BenefitDescription
Versioned ModulesSemantic versioning for all infrastructure components
ReusabilityModules can be used across projects
Better TestingCI/CD validates module changes before deployment
Clear SeparationCatalog (what) vs Live (where/how)
Terrateam StacksProper dependency management and deployment ordering
Industry StandardFollows Gruntwork best practices

Repositories​

Infrastructure Modules (Catalog)​

Infrastructure Live​

Modules Extracted (v1.0.0)​

Foundation Layer​

  • bootstrap - S3 + DynamoDB for Terraform state
  • vpc - HIPAA-compliant VPC with multi-AZ support

Compute Layer​

  • ecs-cluster - ECS Fargate cluster with Spot support
  • ecr - Container image repositories

Data Layer​

  • rds - PostgreSQL database with HIPAA encryption
  • db-init-lambda - Database initialization Lambda

Orchestration Layer​

  • temporal - Self-hosted Temporal workflow engine
  • terrateam - Self-hosted Terrateam on ECS
  • nightly-scheduler - Cost-saving scheduler for ECS/RDS
  • infra-orchestrator - Infrastructure orchestration Lambda

Security Layer​

  • bastion - On-demand bastion host with CloudWatch monitoring
  • bastion-orchestrator - Bastion lifecycle management Lambda
  • ip-whitelist - Dynamic IP whitelist management
  • compliance - AWS Config HIPAA compliance rules
  • scp-policies - Service Control Policies for AWS Organizations

Integration Layer​

  • slack-bot - Slack ChatOps integration

Terrateam Stacks Configuration​

The live repository uses Terrateam stacks for proper dependency management:

Layer-Based Stacks​

  1. Foundation - bootstrap, vpc (no dependencies)
  2. Compute - ecs-cluster, ecr (depends on foundation)
  3. Data - rds, db-init-lambda (depends on foundation)
  4. Orchestration - temporal, terrateam, nightly-scheduler, infra-orchestrator (depends on compute + data)
  5. Security - bastion, bastion-orchestrator, ip-whitelist, compliance, scp-policies (depends on foundation)
  6. Integration - slack-bot (depends on all other layers)

Environment-Based Stacks​

  • Dev - Auto-plan enabled, manual approval required
  • Staging - Applies after dev
  • Prod - Applies after staging

Validation Results​

Git Source Test​

cd docustack-infrastructure-live/dev/us-east-1/vpc
terragrunt init

Result:

INFO  Downloading Terraform configurations from 
git::ssh://git@github.com:docustackapp/docustack-infrastructure-modules.git?ref=v1.0.0

State Preservation​

  • All Terraform state files remain in original S3 buckets
  • No resources recreated during migration
  • Module source changes only (infrastructure unchanged)

Rollback Procedure​

If issues arise, you can rollback by:

  1. Revert to local modules temporarily:

    cd docustack-infrastructure-live/_envcommon
    # Change Git sources back to local paths
    sed -i '' 's|git::git@github.com:docustackapp/docustack-infrastructure-modules.git//modules/\([^?]*\)?ref=v1.0.0|${dirname(find_in_parent_folders("root.hcl"))}/modules/\1|g' *.hcl

  2. Copy modules back to live repo:

    cp -r /path/to/docustack-mono/infrastructure/modules docustack-infrastructure-live/

  3. Run terragrunt plan to verify no changes

Testing Checklist​

Before fully migrating production:

  • Git source downloads correctly from GitHub
  • v1.0.0 tag exists and is accessible
  • Terrateam stacks configuration is valid
  • Full dev environment deployment test
  • Terraform plan shows 0 changes for existing resources
  • Terrateam PR workflow works with new repo
  • All team members have access to both repositories
  • CI/CD pipelines updated (if any)

Support​

For questions or issues: