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**:
```hcl
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**:
```hcl
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**:
```hcl
subnet_id = azurerm_subnet.frontend.id
```

**After**:
```hcl
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:

```hcl
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