the_order/docs/deployment/azure/ENVIRONMENT_SETUP.md

Azure Environment Setup Guide

Last Updated: 2025-01-27
Status: Complete Setup Guide

Overview

This guide explains how to configure Azure deployments using environment variables from .env files.

Prerequisites

1. Azure CLI installed and logged in

   az login
   az account list
   az account set --subscription <subscription-id>
   

2. Terraform installed (>= 1.5.0)

   terraform version
   

3. Environment file created

   • Copy infra/terraform/.env.example to .env or infra/terraform/.env
   • Fill in your Azure credentials

Environment Variables

Required Variables

# Azure Authentication
ARM_SUBSCRIPTION_ID="your-subscription-id"
ARM_TENANT_ID="your-tenant-id"

# Optional: Service Principal (if not using Azure CLI)
ARM_CLIENT_ID="your-client-id"
ARM_CLIENT_SECRET="your-client-secret"

Configuration Variables

# Azure Region (no US regions)
ARM_LOCATION="westeurope"

# Environment
TF_VAR_environment="dev"  # dev, stage, or prod

# Resource Names
TF_VAR_resource_group_name="the-order-rg"
TF_VAR_storage_account_name="theorderdev"  # Must be globally unique
TF_VAR_key_vault_name="the-order-kv-dev"   # Must be globally unique

Setup Steps

Step 1: Create Environment File

# Copy example file
cp infra/terraform/.env.example .env

# Or use Terraform-specific location
cp infra/terraform/.env.example infra/terraform/.env

# Edit with your values
nano .env  # or your preferred editor

Step 2: Load Environment Variables

# Load variables
source infra/scripts/azure-load-env.sh

# Verify
echo $ARM_SUBSCRIPTION_ID
echo $ARM_TENANT_ID

Step 3: Deploy Infrastructure

# Option 1: Use deployment script (recommended)
./infra/scripts/azure-deploy.sh

# Option 2: Manual Terraform
cd infra/terraform
terraform init
terraform plan
terraform apply

Resource Configuration

Resource Group

• Name: the-order-rg-{environment}
• Location: westeurope (or other non-US region)
• Tags: Environment, Project, ManagedBy

Storage Account

• Name: Must be globally unique (lowercase, alphanumeric)
• Tier: Standard
• Replication: LRS (dev), GRS (prod)
• Purpose: Document storage, CDN origin

Key Vault

• Name: Must be globally unique
• SKU: Standard
• Soft Delete: Enabled (7 days retention)
• Purge Protection: Enabled for production

AKS Cluster

• Name: the-order-aks-{environment}
• Kubernetes Version: 1.28+
• Node Count: 2 (dev), auto-scaling (prod)
• VM Size: Standard_B2s (dev), Standard_D2s_v3 (prod)

CDN

• Profile: theorder-cdn-{environment}
• Endpoint: theorder-cdn-endpoint-{environment}
• SKU: Standard_Microsoft

Secrets Management

Storing Secrets in Key Vault

# Set secret in Key Vault
az keyvault secret set \
  --vault-name <key-vault-name> \
  --name "database-url" \
  --value "postgresql://..."

# List secrets
az keyvault secret list --vault-name <key-vault-name>

Using External Secrets Operator

Secrets are automatically synced from Key Vault to Kubernetes using External Secrets Operator. See infra/k8s/base/external-secrets.yaml.

Verification

Check Azure Resources

# List resource groups
az group list --query "[?contains(name, 'the-order')]"

# List storage accounts
az storage account list --query "[?contains(name, 'theorder')]"

# List Key Vaults
az keyvault list --query "[?contains(name, 'the-order')]"

# List AKS clusters
az aks list --query "[?contains(name, 'the-order')]"

Check Kubernetes Access

# Get kubeconfig
az aks get-credentials \
  --resource-group <resource-group> \
  --name <aks-cluster-name>

# Verify access
kubectl get nodes
kubectl get namespaces

Troubleshooting

Authentication Issues

# Re-authenticate with Azure CLI
az login
az account set --subscription <subscription-id>

# Verify current subscription
az account show

Terraform Issues

# Re-initialize Terraform
cd infra/terraform
terraform init -upgrade

# Validate configuration
terraform validate

# Check state
terraform state list

Resource Naming Conflicts

If you get "name already taken" errors:

1. Choose a more unique name
2. Use a different Azure region
3. Delete the conflicting resource (if safe)

Environment-Specific Configurations

Development

• Replication: LRS (lower cost)
• Node Count: 2 (fixed)
• Retention: 30 days
• Purge Protection: Disabled

Staging

• Replication: GRS
• Node Count: 2-5 (auto-scaling)
• Retention: 60 days
• Purge Protection: Enabled

Production

• Replication: GRS or ZRS
• Node Count: 3-10 (auto-scaling)
• Retention: 90 days
• Purge Protection: Enabled
• Backup: Enabled
• Monitoring: Full observability

Next Steps

After infrastructure is deployed:

1. Configure Kubernetes secrets (via External Secrets Operator)
2. Deploy services to AKS
3. Set up monitoring (Prometheus/Grafana)
4. Configure logging (Fluentd/OpenSearch)
5. Set up CI/CD pipelines

See other deployment guides for details.

---

Last Updated: 2025-01-27