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
247
docs/deployment/azure/ENVIRONMENT_SETUP.md
Normal file
247
docs/deployment/azure/ENVIRONMENT_SETUP.md
Normal file
@@ -0,0 +1,247 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user