the_order/infra/terraform/EXECUTION_GUIDE.md

Azure Infrastructure - Execution Guide

Last Updated: 2025-01-27
Default Region: West Europe (westeurope)
Policy: No US Commercial or Government regions

---

Prerequisites

Before executing Terraform, ensure you have:

1. ✅ Azure CLI installed

   az --version
   

2. ✅ Logged into Azure

   az login
   az account show
   

3. ✅ Required permissions

   • Subscription Contributor or Owner role
   • Ability to create resource groups
   • Ability to register resource providers

---

Step-by-Step Execution

Step 1: Run Azure Setup Scripts

Execute the setup scripts to prepare your Azure subscription:

# Navigate to project root
cd /home/intlc/projects/the_order

# Run complete setup (recommended)
./infra/scripts/azure-setup.sh

This will:

• List all non-US Azure regions
• Register all 13 required resource providers
• Check quotas for primary regions
• Generate reports

Expected Output Files:

• azure-regions.txt - List of available regions
• azure-quotas.txt - Quota information for primary regions

Step 2: Verify Resource Provider Registration

# Run provider registration script
./infra/scripts/azure-register-providers.sh

Expected Output:

✓ Microsoft.ContainerService - Registered
✓ Microsoft.KeyVault - Registered
✓ Microsoft.Storage - Registered
...
✓ All required resource providers are registered!

If any providers are not registered, the script will register them automatically.

Step 3: Review Quotas

# Check quotas for all regions
./infra/scripts/azure-check-quotas.sh

Review the output file:

cat azure-quotas-all-regions.txt

Ensure you have sufficient quotas for:

• VM cores (for AKS nodes)
• Storage accounts
• Network resources

Step 4: Initialize Terraform

# Navigate to Terraform directory
cd infra/terraform

# Initialize Terraform (downloads providers)
terraform init

Expected Output:

Initializing the backend...
Initializing provider plugins...
- Finding hashicorp/azurerm versions matching "~> 3.0"...
- Installing hashicorp/azurerm v3.x.x...
Terraform has been successfully initialized!

Step 5: Create Initial Infrastructure (State Storage)

Before using remote state, create the storage account locally:

# Review the plan
terraform plan -target=azurerm_resource_group.terraform_state -target=azurerm_storage_account.terraform_state -target=azurerm_storage_container.terraform_state

# Apply to create state storage
terraform apply -target=azurerm_resource_group.terraform_state -target=azurerm_storage_account.terraform_state -target=azurerm_storage_container.terraform_state

Note: This creates the storage account needed for remote state backend.

Step 6: Configure Remote State Backend

After the storage account is created:

1. Get the storage account name:

   terraform output -raw storage_account_name
   # Or check the Terraform state
   terraform show | grep storage_account_name
   

2. Update versions.tf - Uncomment and configure the backend block:

   backend "azurerm" {
     resource_group_name  = "the-order-terraform-state-rg"
     storage_account_name = "<output-from-above>"
     container_name       = "terraform-state"
     key                  = "terraform.tfstate"
   }
   

3. Re-initialize with backend:

   terraform init -migrate-state
   

Step 7: Plan Full Infrastructure

# Review what will be created
terraform plan

# Save plan to file for review
terraform plan -out=tfplan

Review the plan carefully to ensure:

• Correct resource names
• Correct region (should be westeurope)
• No US regions are being used
• Appropriate resource sizes

Step 8: Apply Infrastructure

# Apply the plan
terraform apply

# Or use the saved plan
terraform apply tfplan

Expected Resources Created:

• Resource groups
• Storage accounts
• (Additional resources as you add them)

Step 9: Verify Deployment

# List created resources
az resource list --resource-group the-order-dev-rg --output table

# Check resource group
az group show --name the-order-dev-rg

# Verify region
az group show --name the-order-dev-rg --query location
# Should output: "westeurope"

---

Environment-Specific Deployment

Development Environment

# Set environment variable
export TF_VAR_environment=dev

# Or use -var flag
terraform plan -var="environment=dev"
terraform apply -var="environment=dev"

Staging Environment

terraform plan -var="environment=stage"
terraform apply -var="environment=stage"

Production Environment

# Production requires extra caution
terraform plan -var="environment=prod" -detailed-exitcode
terraform apply -var="environment=prod"

---

Troubleshooting

Error: Resource Provider Not Registered

Symptom:

Error: creating Resource Group: resources.ResourcesClient#CreateOrUpdate: 
Failure sending request: StatusCode=400 -- Original Error: 
Code="MissingSubscriptionRegistration"

Solution:

# Register the provider
az provider register --namespace Microsoft.Resources --wait

# Or run the registration script
./infra/scripts/azure-register-providers.sh

Error: Quota Exceeded

Symptom:

Error: creating Storage Account: storage.AccountsClient#Create: 
Failure sending request: StatusCode=400 -- Original Error: 
Code="SubscriptionQuotaExceeded"

Solution:

1. Check quotas: ./infra/scripts/azure-check-quotas.sh
2. Request quota increase in Azure Portal
3. Or use a different region

Error: Invalid Region

Symptom:

Error: invalid location "us-east-1"

Solution:

• Ensure you're using westeurope or another non-US region
• Check variables.tf - default should be westeurope
• Terraform validation should prevent US regions

Error: Storage Account Name Already Exists

Symptom:

Error: creating Storage Account: storage.AccountsClient#Create: 
Failure sending request: StatusCode=409 -- Original Error: 
Code="StorageAccountAlreadyTaken"

Solution:

• Storage account names must be globally unique
• Modify the name in storage.tf or use a different project name

---

Best Practices

1. Always Review Plans

# Always review before applying
terraform plan -out=tfplan
terraform show tfplan

2. Use Workspaces for Multiple Environments

# Create workspace for dev
terraform workspace new dev

# Create workspace for prod
terraform workspace new prod

# Switch between workspaces
terraform workspace select dev

3. Version Control

• ✅ Commit Terraform files to version control
• ❌ Never commit .tfstate files
• ✅ Use remote state backend (Azure Storage)
• ✅ Use .tfvars files for environment-specific values (add to .gitignore)

4. State Management

• ✅ Use remote state backend
• ✅ Enable state locking (automatic with Azure Storage)
• ✅ Enable versioning on storage account
• ✅ Regular backups of state

5. Security

• ✅ Use Azure Key Vault for secrets
• ✅ Use Managed Identities where possible
• ✅ Enable soft delete on Key Vault
• ✅ Enable versioning on storage accounts

---

Next Steps

After initial infrastructure is created:

1. Create Azure Key Vault

   • For secrets management
   • See key-vault.tf (to be created)

2. Create AKS Cluster

   • For Kubernetes deployment
   • See aks.tf (to be created)

3. Create PostgreSQL Database

   • For application database
   • See database.tf (to be created)

4. Create Container Registry

   • For container images
   • See container-registry.tf (to be created)

5. Configure Networking

   • Virtual networks, subnets, NSGs
   • See network.tf (to be created)

---

Quick Reference Commands

# Setup
./infra/scripts/azure-setup.sh
./infra/scripts/azure-register-providers.sh

# Terraform
cd infra/terraform
terraform init
terraform plan
terraform apply
terraform destroy

# Verification
az resource list --resource-group the-order-dev-rg
az group show --name the-order-dev-rg
terraform output

---

Support

• Resource Providers: See AZURE_RESOURCE_PROVIDERS.md
• Scripts: See infra/scripts/README.md
• Troubleshooting: See sections above
• Azure CLI Docs: https://docs.microsoft.com/en-us/cli/azure/

---

Ready to deploy! 🚀