the_order/docs/deployment/azure/DOTENV_SETUP.md

# Using .env File for Azure Deployments

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

## Overview

This guide explains how to use the `.env` file in the project root to configure all Azure deployments, ensuring consistent configuration across Terraform, Kubernetes, and application services.

## Setup

### Step 1: Create/Update .env File

The `.env` file should be in the project root (`/home/intlc/projects/the_order/.env`).

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"

# Azure Configuration
ARM_LOCATION="westeurope"  # No US regions
TF_VAR_environment="dev"   # dev, stage, or prod
```

### Step 2: Validate Environment

```bash
# Validate all required variables are set
source infra/scripts/azure-validate-env.sh
```

This script will:
- ✅ Check for required variables
- ✅ Set defaults for optional variables
- ✅ Verify Azure CLI authentication
- ✅ Export Terraform variables

### Step 3: Sync to Terraform

```bash
# Generate terraform.tfvars from .env
./infra/scripts/azure-sync-env-to-terraform.sh
```

This creates `infra/terraform/terraform.tfvars` with all values from `.env`.

### Step 4: Deploy Infrastructure

```bash
# Complete deployment using .env values
./infra/scripts/azure-deploy.sh
```

## How It Works

### Environment Variable Flow

```
.env file
    ↓
azure-validate-env.sh (validates & exports)
    ↓
azure-sync-env-to-terraform.sh (creates terraform.tfvars)
    ↓
Terraform (creates Azure resources)
    ↓
Terraform outputs (Key Vault URI, Storage Account, etc.)
    ↓
azure-update-k8s-secrets.sh (updates Kubernetes configs)
    ↓
Kubernetes External Secrets (syncs from Key Vault)
```

### Variable Mapping

| .env Variable | Terraform Variable | Kubernetes Config |
|--------------|-------------------|-------------------|
| `ARM_SUBSCRIPTION_ID` | `TF_VAR_subscription_id` | Via Key Vault |
| `ARM_TENANT_ID` | `TF_VAR_tenant_id` | External Secrets |
| `ARM_LOCATION` | `TF_VAR_azure_region` | ConfigMap |
| `TF_VAR_environment` | `TF_VAR_environment` | ConfigMap |
| `TF_VAR_resource_group_name` | `TF_VAR_resource_group_name` | ConfigMap |
| `TF_VAR_storage_account_name` | `TF_VAR_storage_account_name` | External Secrets |
| `TF_VAR_key_vault_name` | `TF_VAR_key_vault_name` | External Secrets |

## Resource Naming

Resources are named using values from `.env`:

- **Resource Group**: `TF_VAR_resource_group_name` or `the-order-rg-{environment}`
- **Storage Account**: `TF_VAR_storage_account_name` or auto-generated
- **Key Vault**: `TF_VAR_key_vault_name` or `the-order-kv-{environment}`
- **AKS Cluster**: `TF_VAR_aks_cluster_name` or `the-order-aks-{environment}`

## Secrets Management

### Storing Secrets

Secrets are stored in Azure Key Vault and synced to Kubernetes:

1. **Store in Key Vault** (via Azure CLI or Terraform):
   ```bash
   az keyvault secret set \
     --vault-name <key-vault-name> \
     --name "database-url" \
     --value "postgresql://..."
   ```

2. **Sync to Kubernetes** (automatic via External Secrets Operator):
   - External Secrets Operator reads from Key Vault
   - Creates Kubernetes secrets automatically
   - Updates when Key Vault secrets change

### Accessing Secrets

Services access secrets via:
- **Kubernetes Secrets**: Created by External Secrets Operator
- **Environment Variables**: Injected into pods
- **Key Vault Direct**: For services with managed identity

## Verification

### Check Terraform Variables

```bash
cd infra/terraform
terraform plan  # Shows what will be created with current .env values
```

### Check Kubernetes Config

```bash
# View ConfigMap
kubectl get configmap azure-config -n the-order -o yaml

# View External Secrets
kubectl get externalsecret azure-secrets -n the-order -o yaml

# View synced secrets
kubectl get secret the-order-secrets -n the-order -o yaml
```

## Troubleshooting

### Variables Not Found

```bash
# Re-validate environment
source infra/scripts/azure-validate-env.sh

# Check .env file exists
ls -la .env

# Verify variables are set
echo $ARM_SUBSCRIPTION_ID
echo $ARM_TENANT_ID
```

### Terraform Can't Find Variables

```bash
# Re-sync to Terraform
./infra/scripts/azure-sync-env-to-terraform.sh

# Check terraform.tfvars
cat infra/terraform/terraform.tfvars
```

### Kubernetes Secrets Not Syncing

```bash
# Update Kubernetes configs
./infra/scripts/azure-update-k8s-secrets.sh

# Check External Secrets Operator
kubectl get pods -n external-secrets-system

# Check External Secret status
kubectl describe externalsecret azure-secrets -n the-order
```

## Best Practices

1. **Never commit .env file** - It's in `.gitignore`
2. **Use different .env files** for different environments
3. **Store sensitive values in Key Vault** - Not in .env
4. **Validate before deploying** - Always run validation script
5. **Keep .env.example updated** - Document all variables

## Example .env File

```bash
# Azure Authentication
ARM_SUBSCRIPTION_ID="12345678-1234-1234-1234-123456789012"
ARM_TENANT_ID="87654321-4321-4321-4321-210987654321"

# Azure Configuration
ARM_LOCATION="westeurope"
TF_VAR_environment="dev"

# Resource Naming
TF_VAR_resource_group_name="the-order-rg-dev"
TF_VAR_storage_account_name="theorderdev12345"
TF_VAR_key_vault_name="the-order-kv-dev"

# AKS Configuration
TF_VAR_aks_cluster_name="the-order-aks-dev"
TF_VAR_aks_node_count=2
TF_VAR_aks_vm_size="Standard_B2s"
```

---

**Last Updated**: 2025-01-27