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:

# 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

# 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

# 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

# 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):

   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

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

Check Kubernetes Config

# 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

# 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

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

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

Kubernetes Secrets Not Syncing

# 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

# 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