docs/TERRAFORM_MIGRATION_GUIDE.md

Terraform Module Migration Guide

Date: 2025-01-27 Purpose: Guide for migrating projects to use shared Terraform modules Status: Complete

---

Overview

This guide provides step-by-step instructions for migrating projects to use the shared Terraform modules located in infrastructure/terraform/modules/.

---

Available Modules

Azure Modules

1. Networking (azure/networking)

   • Virtual networks
   • Subnets
   • Network security groups

2. Key Vault (azure/keyvault)

   • Key Vault creation
   • Access policies
   • RBAC

3. Storage (azure/storage)

   • Storage accounts
   • Containers
   • File shares
   • Queues
   • Tables

Kubernetes Modules

1. Namespace (kubernetes/namespace)
   • Namespace creation
   • Resource quotas
   • Limit ranges

---

Migration Steps

Step 1: Review Current Infrastructure

1. Identify existing Terraform code in your project
2. Document current resources
3. Map resources to shared modules

Step 2: Update Terraform Configuration

Example: Migrating to Networking Module

Before:

resource "azurerm_virtual_network" "main" {
  name                = "vnet-example"
  address_space       = ["10.0.0.0/16"]
  location            = "eastus"
  resource_group_name = "rg-example"
}

resource "azurerm_subnet" "frontend" {
  name                 = "snet-frontend"
  resource_group_name  = "rg-example"
  virtual_network_name = azurerm_virtual_network.main.name
  address_prefixes     = ["10.0.1.0/24"]
}

After:

module "networking" {
  source = "../../infrastructure/terraform/modules/azure/networking"

  resource_group_name = "rg-example"
  location           = "eastus"
  vnet_name          = "vnet-example"
  address_space      = ["10.0.0.0/16"]

  subnets = {
    frontend = {
      name             = "snet-frontend"
      address_prefixes = ["10.0.1.0/24"]
      service_endpoints = []
    }
  }
}

Step 3: Update References

Update any references to old resources:

Before:

subnet_id = azurerm_subnet.frontend.id

After:

subnet_id = module.networking.subnet_ids["frontend"]

Step 4: Test Migration

1. Run terraform init to download modules
2. Run terraform plan to review changes
3. Verify no unexpected changes
4. Run terraform apply if changes are correct

---

Best Practices

Module Versioning

Use version constraints:

module "networking" {
  source = "../../infrastructure/terraform/modules/azure/networking"
  # Or use git source with version
  # source = "git::https://github.com/org/repo.git//modules/azure/networking?ref=v1.0.0"
}

State Migration

If resources already exist:

1. Import existing resources to module state
2. Use terraform state mv to reorganize
3. Verify state after migration

Testing

1. Test in dev/staging first
2. Verify all outputs
3. Check resource dependencies
4. Validate security configurations

---

Common Migration Patterns

Pattern 1: Direct Replacement

Replace resource blocks with module calls.

Pattern 2: Gradual Migration

Migrate one resource type at a time.

Pattern 3: New Projects

Use modules from the start for new projects.

---

Troubleshooting

Module Not Found

Issue: Error: Failed to download module

Solution:

• Check module path
• Run terraform init
• Verify module exists

State Conflicts

Issue: Error: Resource already exists

Solution:

• Import existing resources
• Use terraform state mv
• Review state file

Output Not Found

Issue: Error: Reference to undeclared output

Solution:

• Check module outputs
• Verify output name
• Review module documentation

---

Migration Checklist

• Review current infrastructure
• Identify modules to use
• Update Terraform configuration
• Update resource references
• Test in dev/staging
• Review terraform plan
• Apply changes
• Verify resources
• Update documentation
• Remove old code

---

Last Updated: 2025-01-27