Skip to content

Local Terraform Testing

This document provides guidance on how to test Terraform modules locally during development, allowing you to iterate quickly without publishing modules to Terraform Cloud.

📋 Overview

Local testing allows you to:

  • ✅ Test module changes before publishing to Terraform Cloud
  • 🐛 Debug module issues more efficiently
  • 🚀 Develop and validate new module features locally
  • 🌍 Ensure module compatibility across different environments

✅ Prerequisites

  • 💻 Terraform installed locally
  • 📁 Access to the module source code
  • ☁️ Access to Terraform Cloud workspace (credentials handled by Terraform Cloud)
  • 📖 Understanding of swap-terraform-modules.md process

🎯 Step 1: Prepare Your Local Environment

  1. 📥 Clone or pull the latest version of the module repository
  2. 📂 Ensure you have the module code locally (e.g., c:\forge\src\terraform\saif-web-service)
  3. 🔐 Verify your Terraform Cloud workspace access is configured

🔄 Step 2: Modify Module Source

☁️ Before (Terraform Cloud Module)

module "api-service" {
  source  = "app.terraform.io/SAIFCorp/api-service/saif"
  version = "~>2.1.0"
  # insert required variables here
  project_id = var.project_id
  environment = var.environment
}

💻 After (Local Module)

module "api-service" {
  source = "c:\\forge\\src\\terraform\\saif-api-service"
  # Note: Remove version constraint for local modules
  # insert required variables here
  project_id = var.project_id
  environment = var.environment
}

📚 Step 3: Common Local Module Patterns

🌐 Web Service Module

# From Terraform Cloud
module "web-service" {
  source  = "app.terraform.io/SAIFCorp/web-service/saif"
  version = "~>2.1.0"
  # variables...
}

# To Local
module "web-service" {
  source = "c:\\forge\\src\\terraform\\saif-web-service"
  # variables...
}

🔌 API Service Module

# From Terraform Cloud
module "api-service" {
  source  = "app.terraform.io/SAIFCorp/api-service/saif"
  version = "~>2.1.0"
  # variables...
}

# To Local
module "api-service" {
  source = "c:\\forge\\src\\terraform\\saif-api-service"
  # variables...
}

🔒 Security Module

# From Terraform Cloud
module "security" {
  source  = "app.terraform.io/SAIFCorp/security/azure//modules/application"
  version = "~>2.1.0"
  # variables...
}

# To Local
module "security" {
  source = "c:\\forge\\src\\terraform\\azure-security\\modules\\application"
  # variables...
}

🧪 Step 4: Testing Process

  1. 🚀 Initialize Terraform
terraform init
  1. 📋 Plan Changes
terraform plan
  1. ⚡ Apply Changes (if safe)
terraform apply
  1. ✅ Validate Results
  2. 🔍 Check Azure resources in the portal
  3. ✔️ Verify expected behavior
  4. 🧪 Test application functionality

⚠️ Step 5: Important Considerations

📁 Path Separators

  • 🖥️ Use double backslashes (\\) or forward slashes (/) in Windows paths
  • 💡 Example: c:\\forge\\src\\terraform\\module-name or c:/forge/src/terraform/module-name

🏷️ Version Constraints

  • ❌ Remove version constraints when using local modules
  • 🚫 Local modules don't support version pinning
  • 📍 Version is implicit based on your local code state

📍 Relative vs Absolute Paths

# 👍 Absolute path (recommended)
source = "c:\\forge\\src\\terraform\\saif-web-service"

# ⚠️ Relative path (use with caution)
source = "..\\..\\saif-web-service"

🔄 Step 6: Switch Back to Terraform Cloud

⚠️ CRITICAL: Always switch back to Terraform Cloud modules before committing!

After testing, revert your changes:

# Switch back from local
module "api-service" {
  source = "c:\\forge\\src\\terraform\\saif-api-service"
  # variables...
}

# To Terraform Cloud
module "api-service" {
  source  = "app.terraform.io/SAIFCorp/api-service/saif"
  version = "~>2.1.0"
  # variables...
}

💡 Best Practices

1. 🌿 Use Git Branches

  • 🔀 Create a feature branch for local testing
  • 🏗️ Keep local module changes separate from production code

2. 📝 Document Changes

  • 📋 Keep track of what you're testing
  • 📄 Document any temporary modifications

3. 🧩 Test Incrementally

  • 👶 Test small changes first
  • ✅ Validate each change before proceeding

4. 🧹 Clean Up

  • 🔄 Always revert to Terraform Cloud modules
  • 🗑️ Remove any temporary test resources

5. ✅ Validate Before Commit

# Ensure you're back to using Terraform Cloud modules
Select-String -Path "*.tf" -Pattern "source.*c:\\\\"
# Should return no results before committing

🛠️ Troubleshooting

🚨 Common Issues

  1. 📂 Path Not Found
  2. 🔍 Verify the local module path exists

  3. ✔️ Check path separator usage (use \\ or /)

  4. 🔗 Module Dependencies

  5. 📦 Ensure all nested modules are available locally
  6. 🔄 Update nested module sources if needed

🔧 Recovery Steps

If you encounter state issues:

  1. 🔄 Reinitialize if needed
terraform init -reconfigure

📝 Summary

Local Terraform module testing is a powerful development technique that allows for rapid iteration and debugging. Remember to:

  1. 🖥️ Use proper path syntax for your operating system
  2. 🚫 Remove version constraints for local modules
  3. 🧪 Test thoroughly before publishing changes
  4. ⚠️ Always switch back to Terraform Cloud modules before committing

This approach enables efficient module development while maintaining production stability.