Azure Deployment Guide

This comprehensive guide walks you through deploying AquaGen API to Microsoft Azure cloud platform.

🎯 Overview

AquaGen API is designed as a cloud-native application optimized for Azure. This deployment uses the following Azure services:

📋 Prerequisites

Before you begin, ensure you have:

• Azure Subscription with sufficient credits
• Azure CLI installed (az --version)
• Python 3.8+ for local testing
• Git for source control
• Admin access to create Azure resources

🚀 Quick Deployment

Step 1: Clone Repository

git clone https://github.com/Fluxgentech/aquagenapi.git
cd aquagenapi

Step 2: Login to Azure

az login
az account set --subscription "Your-Subscription-Name"

Step 3: Run Deployment Script

# Set environment variables
export RESOURCE_GROUP="aquagen-rg"
export LOCATION="eastus"
export APP_NAME="aquagen-api"

# Create resource group
az group create --name $RESOURCE_GROUP --location $LOCATION

# Deploy resources
./scripts/deploy_azure.sh

🏗️ Manual Deployment

1. Create Resource Group

az group create \
  --name aquagen-rg \
  --location eastus

2. Create Cosmos DB Account

az cosmosdb create \
  --name aquagen-cosmos \
  --resource-group aquagen-rg \
  --kind GlobalDocumentDB \
  --default-consistency-level Session \
  --locations regionName=eastus failoverPriority=0 isZoneRedundant=False

Create Database and Containers:

# Create database
az cosmosdb sql database create \
  --account-name aquagen-cosmos \
  --resource-group aquagen-rg \
  --name aquagen_db

# Create containers
containers=(
  "industries_container:/id"
  "users_container:/industryId"
  "devices_data_container:/industryId"
  "processed_data_container:/industryId"
  "notification_container:/industryId"
  "standard_categories_master_container:/id"
  "industry_metrics_container:/industryId"
  "insights_data_container:/industryId"
  "aqua_gpt_container:/industryId"
  "global_logs_container:/date"
  "ip_logs_container:/date"
)

for container_info in "${containers[@]}"; do
  IFS=':' read -r container partition <<< "$container_info"
  az cosmosdb sql container create \
    --account-name aquagen-cosmos \
    --resource-group aquagen-rg \
    --database-name aquagen_db \
    --name $container \
    --partition-key-path $partition \
    --throughput 400
done

3. Create Azure Key Vault

az keyvault create \
  --name aquagen-keyvault \
  --resource-group aquagen-rg \
  --location eastus \
  --enable-soft-delete true \
  --retention-days 90

Add Secrets:

# Database secrets
az keyvault secret set \
  --vault-name aquagen-keyvault \
  --name COSMOSDBENDPOINT \
  --value "https://aquagen-cosmos.documents.azure.com:443/"

az keyvault secret set \
  --vault-name aquagen-keyvault \
  --name COSMOSDBKEY \
  --value "YOUR_COSMOS_PRIMARY_KEY"

# JWT secret
az keyvault secret set \
  --vault-name aquagen-keyvault \
  --name SECRET-KEY \
  --value "$(openssl rand -hex 32)"

# Azure AD secrets
az keyvault secret set \
  --vault-name aquagen-keyvault \
  --name AZURE-AD-APP-ID \
  --value "YOUR_AAD_APP_ID"

# Add other secrets...

4. Create IoT Hub

az iot hub create \
  --name aquagen-iothub \
  --resource-group aquagen-rg \
  --sku S1 \
  --partition-count 4

Get Connection String:

az iot hub connection-string show \
  --hub-name aquagen-iothub \
  --output tsv

# Add to Key Vault
az keyvault secret set \
  --vault-name aquagen-keyvault \
  --name IOTHUB-CONNECTION-STRING \
  --value "YOUR_IOT_HUB_CONNECTION_STRING"

5. Create Application Insights

az monitor app-insights component create \
  --app aquagen-insights \
  --location eastus \
  --resource-group aquagen-rg \
  --application-type web

Get Instrumentation Key:

az monitor app-insights component show \
  --app aquagen-insights \
  --resource-group aquagen-rg \
  --query connectionString \
  --output tsv

6. Create Blob Storage

az storage account create \
  --name aquagenstorage \
  --resource-group aquagen-rg \
  --location eastus \
  --sku Standard_LRS

# Create container for reports
az storage container create \
  --name reports \
  --account-name aquagenstorage

# Get connection string
az storage account show-connection-string \
  --name aquagenstorage \
  --resource-group aquagen-rg \
  --output tsv

7. Create App Service Plan

az appservice plan create \
  --name aquagen-plan \
  --resource-group aquagen-rg \
  --sku P1V2 \
  --is-linux

Pricing Tiers:

Tier	vCPU	RAM	Storage	Price/Month*
B1	1	1.75 GB	10 GB	~$55
P1V2	1	3.5 GB	250 GB	~$85
P2V2	2	7 GB	250 GB	~$170

*Approximate pricing, check Azure pricing calculator

8. Create Web App

az webapp create \
  --resource-group aquagen-rg \
  --plan aquagen-plan \
  --name aquagen-api \
  --runtime "PYTHON:3.10"

9. Configure App Settings

# Set environment variables
az webapp config appsettings set \
  --resource-group aquagen-rg \
  --name aquagen-api \
  --settings \
    ENVIRONMENT=production \
    APPLICATIONINSIGHTS_CONNECTION_STRING="YOUR_INSIGHTS_CONNECTION_STRING" \
    AZURE_CLIENT_ID="YOUR_SERVICE_PRINCIPAL_CLIENT_ID" \
    AZURE_TENANT_ID="YOUR_TENANT_ID" \
    AZURE_CLIENT_SECRET="YOUR_SERVICE_PRINCIPAL_SECRET" \
    KEY_VAULT_NAME="aquagen-keyvault"

10. Enable Managed Identity

# Enable system-assigned managed identity
az webapp identity assign \
  --name aquagen-api \
  --resource-group aquagen-rg

# Get the principal ID
PRINCIPAL_ID=$(az webapp identity show \
  --name aquagen-api \
  --resource-group aquagen-rg \
  --query principalId \
  --output tsv)

# Grant Key Vault access
az keyvault set-policy \
  --name aquagen-keyvault \
  --object-id $PRINCIPAL_ID \
  --secret-permissions get list

11. Deploy Application Code

Using Git Deployment:

# Configure deployment source
az webapp deployment source config-local-git \
  --name aquagen-api \
  --resource-group aquagen-rg

# Get deployment URL
az webapp deployment list-publishing-credentials \
  --name aquagen-api \
  --resource-group aquagen-rg \
  --query scmUri \
  --output tsv

# Add Azure remote
git remote add azure https://YOUR_DEPLOYMENT_URL

# Push code
git push azure production:master

Using ZIP Deployment:

# Create deployment package
zip -r deploy.zip . -x "*.git*" ".venv/*" "__pycache__/*"

# Deploy
az webapp deployment source config-zip \
  --resource-group aquagen-rg \
  --name aquagen-api \
  --src deploy.zip

12. Configure Custom Domain (Optional)

# Map custom domain
az webapp config hostname add \
  --webapp-name aquagen-api \
  --resource-group aquagen-rg \
  --hostname api.yourdomain.com

# Enable HTTPS
az webapp config ssl bind \
  --certificate-thumbprint YOUR_CERT_THUMBPRINT \
  --ssl-type SNI \
  --name aquagen-api \
  --resource-group aquagen-rg

🔐 Security Configuration

1. Network Security

Enable Firewall Rules:

# Restrict Cosmos DB access
az cosmosdb network-rule add \
  --resource-group aquagen-rg \
  --name aquagen-cosmos \
  --subnet YOUR_SUBNET_ID

# Enable virtual network integration
az webapp vnet-integration add \
  --name aquagen-api \
  --resource-group aquagen-rg \
  --vnet YOUR_VNET_NAME \
  --subnet YOUR_SUBNET_NAME

2. Authentication

Configure Azure AD:

az webapp auth update \
  --name aquagen-api \
  --resource-group aquagen-rg \
  --enabled true \
  --action LoginWithAzureActiveDirectory \
  --aad-client-id YOUR_AAD_APP_ID \
  --aad-token-issuer-url https://sts.windows.net/YOUR_TENANT_ID/

3. CORS Configuration

az webapp cors add \
  --name aquagen-api \
  --resource-group aquagen-rg \
  --allowed-origins https://yourdomain.com

📊 Monitoring Setup

Application Insights Configuration

Enable Advanced Monitoring:

# Enable detailed telemetry
az monitor app-insights component update \
  --app aquagen-insights \
  --resource-group aquagen-rg \
  --retention-time 90

Create Alerts:

# Alert on high response time
az monitor metrics alert create \
  --name high-response-time \
  --resource-group aquagen-rg \
  --scopes /subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/aquagen-rg/providers/Microsoft.Web/sites/aquagen-api \
  --condition "avg requests/duration > 1000" \
  --description "Alert when average response time exceeds 1 second"

# Alert on failures
az monitor metrics alert create \
  --name high-error-rate \
  --resource-group aquagen-rg \
  --scopes /subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/aquagen-rg/providers/Microsoft.Web/sites/aquagen-api \
  --condition "count requests/failed > 10" \
  --description "Alert when error count exceeds 10 in 5 minutes"

🔄 CI/CD Pipeline

GitHub Actions Workflow

Create .github/workflows/azure-deploy.yml:

name: Deploy to Azure

on:
  push:
    branches: [ production ]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2

    - name: Set up Python
      uses: actions/setup-python@v2
      with:
        python-version: '3.10'

    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -r requirements.txt

    - name: Run tests
      run: |
        pytest tests/

    - name: Deploy to Azure
      uses: azure/webapps-deploy@v2
      with:
        app-name: 'aquagen-api'
        publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}

Azure DevOps Pipeline

Create azure-pipelines.yml:

trigger:
  branches:
    include:
    - production

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.10'

- script: |
    pip install -r requirements.txt
    pytest tests/
  displayName: 'Install dependencies and run tests'

- task: AzureWebApp@1
  inputs:
    azureSubscription: 'Your-Service-Connection'
    appName: 'aquagen-api'
    package: '$(System.DefaultWorkingDirectory)'

🚦 Post-Deployment Validation

1. Health Check

curl https://aquagen-api.azurewebsites.net/health

2. Test API Endpoints

# Test report generation
curl -X GET "https://aquagen-api.azurewebsites.net/api/user/report?\
reportType=daily&\
reportFormat=html&\
service=water&\
startDate=09/11/2024" \
-H "Authorization: Bearer YOUR_TOKEN"

3. Monitor Logs

# Stream logs
az webapp log tail \
  --name aquagen-api \
  --resource-group aquagen-rg

# Download logs
az webapp log download \
  --name aquagen-api \
  --resource-group aquagen-rg \
  --log-file logs.zip

🔧 Scaling Configuration

Auto-scaling Rules

# Scale out based on CPU
az monitor autoscale create \
  --resource-group aquagen-rg \
  --resource /subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/aquagen-rg/providers/Microsoft.Web/serverFarms/aquagen-plan \
  --min-count 1 \
  --max-count 5 \
  --count 1

az monitor autoscale rule create \
  --resource-group aquagen-rg \
  --autoscale-name autoscale-aquagen \
  --condition "Percentage CPU > 70 avg 5m" \
  --scale out 1

az monitor autoscale rule create \
  --resource-group aquagen-rg \
  --autoscale-name autoscale-aquagen \
  --condition "Percentage CPU < 30 avg 5m" \
  --scale in 1

💰 Cost Optimization

1. Right-Size Resources

Component	Development	Production
App Service	B1	P1V2/P2V2
Cosmos DB	400 RU/s	1000+ RU/s (auto-scale)
IoT Hub	F1 (Free)	S1
Blob Storage	LRS	GRS

2. Enable Auto-scaling

• Use auto-scaling for App Service
• Enable Cosmos DB auto-scale
• Schedule scale-down during off-hours

3. Monitor Costs

# View costs
az consumption usage list \
  --start-date 2024-11-01 \
  --end-date 2024-11-30

# Set budget alerts
az consumption budget create \
  --amount 500 \
  --budget-name aquagen-budget \
  --category cost \
  --time-grain monthly

🐛 Troubleshooting

Application Not Starting

Check logs:

az webapp log tail --name aquagen-api --resource-group aquagen-rg

Common issues:

• Missing environment variables
• Incorrect Python version
• Dependencies not installed

Database Connection Errors

Verify connection:

# Test Cosmos DB connectivity
az cosmosdb check-name-exists --name aquagen-cosmos

Check firewall rules:

az cosmosdb network-rule list \
  --resource-group aquagen-rg \
  --name aquagen-cosmos

Performance Issues

Check metrics:

• Application Insights response times
• Cosmos DB RU consumption
• App Service CPU/memory usage

---

Deployment Complete!

Your AquaGen API is now running on Azure. Visit https://aquagen-api.azurewebsites.net to access the API.

📚 Next Steps

• Configuration Guide - Configure application settings
• Monitoring Guide - Set up monitoring and alerts
• Scaling Guide - Scale your application