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**
   ```bash
   az login
   az account list
   az account set --subscription <subscription-id>
   ```

2. **Terraform installed** (>= 1.5.0)
   ```bash
   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

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

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

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

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

# Verify
echo $ARM_SUBSCRIPTION_ID
echo $ARM_TENANT_ID
```

### Step 3: Deploy Infrastructure

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

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

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

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

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

# Verify current subscription
az account show
```

### Terraform Issues

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