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**
   ```bash
   az --version
   ```

2. ✅ **Logged into Azure**
   ```bash
   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:

```bash
# 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

```bash
# 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

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

**Review the output file:**
```bash
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

```bash
# 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:

```bash
# 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:**
   ```bash
   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:
   ```hcl
   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:**
   ```bash
   terraform init -migrate-state
   ```

### Step 7: Plan Full Infrastructure

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Set environment variable
export TF_VAR_environment=dev

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

### Staging Environment

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

### Production Environment

```bash
# 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:**
```bash
# 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

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

### 2. Use Workspaces for Multiple Environments

```bash
# 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

```bash
# 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!** 🚀