feat: comprehensive project structure improvements and Cloud for Sovereignty landing zone
- Add Cloud for Sovereignty landing zone architecture and deployment - Implement complete legal document management system - Reorganize documentation with improved navigation - Add infrastructure improvements (Dockerfiles, K8s, monitoring) - Add operational improvements (graceful shutdown, rate limiting, caching) - Create comprehensive project structure documentation - Add Azure deployment automation scripts - Improve repository navigation and organization
This commit is contained in:
defiQUG
221
docs/deployment/azure/DOTENV_SETUP.md
Normal file
221
docs/deployment/azure/DOTENV_SETUP.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user