# ☁️ AIM - Cloud Deployment Guide

Comprehensive guide for deploying AIM to Azure, Google Cloud Platform (GCP), and Amazon Web Services (AWS).

---

## 📋 Table of Contents

1. [Overview](#overview)
2. [Azure Deployment](#-azure-deployment)
3. [Google Cloud Deployment](#-google-cloud-deployment)
4. [AWS Deployment](#-aws-deployment)
5. [Cost Comparison](#-cost-comparison)
6. [Performance Comparison](#-performance-comparison)

---

## Overview

AIM provides one-command deployment scripts for all major cloud providers:

| Cloud Provider | Service | Deployment Time | Cost (Monthly) |
|----------------|---------|-----------------|----------------|
| **Azure** | Container Apps | ~15 minutes | ~$50-100 |
| **Google Cloud** | Cloud Run | ~20 minutes | ~$40-80 |
| **AWS** | ECS Fargate | ~25 minutes | ~$60-120 |

---

## 🔵 Azure Deployment

### Prerequisites

```bash
# Install Azure CLI
# macOS
brew install azure-cli

# Linux
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

# Windows
# Download from https://aka.ms/installazurecliwindows

# Login to Azure
az login
```

### Quick Deploy

```bash
# Set environment variables (optional)
export AIM_RESOURCE_GROUP="aim-production"
export AIM_LOCATION="eastus"

# Run deployment
cd infrastructure/azure
./deploy.sh
```

### What Gets Deployed

- **Container Apps Environment**: Managed Kubernetes environment
- **Azure Container Registry (ACR)**: Private Docker registry
- **PostgreSQL Flexible Server**: Managed database (16GB storage)
- **Azure Cache for Redis**: In-memory cache
- **2 Container Apps**:
  - Backend (Go/Fiber) - 1 vCPU, 2GB RAM
  - Frontend (Next.js) - 0.5 vCPU, 1GB RAM

### Configuration Options

```bash
# Resource Group
export AIM_RESOURCE_GROUP="aim-prod"

# Azure Region (eastus, westus2, centralus, etc.)
export AIM_LOCATION="eastus"

# Container App Environment Name
export AIM_CONTAINER_APP_ENV="aim-environment"

# Container Registry Name (must be globally unique)
export AIM_ACR_NAME="aimregistry123456"

# PostgreSQL Server Name
export AIM_POSTGRES_SERVER="aim-postgres-123456"

# Redis Cache Name
export AIM_REDIS_NAME="aim-redis"
```

### Post-Deployment

```bash
# View deployed resources
az resource list --resource-group $AIM_RESOURCE_GROUP --output table

# View backend logs
az containerapp logs show --name aim-backend --resource-group $AIM_RESOURCE_GROUP

# Scale backend
az containerapp update \
  --name aim-backend \
  --resource-group $AIM_RESOURCE_GROUP \
  --min-replicas 2 \
  --max-replicas 10

# Update backend image
az containerapp update \
  --name aim-backend \
  --resource-group $AIM_RESOURCE_GROUP \
  --image $ACR_NAME.azurecr.io/aim-backend:latest
```

### Custom Domain (Optional)

```bash
# Add custom domain
az containerapp hostname add \
  --name aim-frontend \
  --resource-group $AIM_RESOURCE_GROUP \
  --hostname yourdomain.com

# Bind SSL certificate
az containerapp hostname bind \
  --name aim-frontend \
  --resource-group $AIM_RESOURCE_GROUP \
  --hostname yourdomain.com \
  --certificate-identity /subscriptions/.../certificates/your-cert
```

### Cleanup

```bash
# Delete all resources
az group delete --name $AIM_RESOURCE_GROUP --yes
```

---

## 🟢 Google Cloud Deployment

### Prerequisites

```bash
# Install gcloud CLI
# macOS
brew install --cask google-cloud-sdk

# Linux
curl https://sdk.cloud.google.com | bash

# Windows
# Download from https://cloud.google.com/sdk/docs/install

# Login to GCP
gcloud auth login

# Set project
gcloud config set project YOUR_PROJECT_ID
```

### Quick Deploy

```bash
# Set environment variables (optional)
export GCP_PROJECT_ID="your-project-id"
export GCP_REGION="us-central1"

# Run deployment
cd infrastructure/gcp
./deploy.sh
```

### What Gets Deployed

- **Cloud Run Services**: Serverless containers
- **Artifact Registry**: Private Docker registry
- **Cloud SQL (PostgreSQL)**: Managed database
- **Memorystore (Redis)**: In-memory cache
- **VPC Access Connector**: Private networking
- **2 Cloud Run Services**:
  - Backend - 1 vCPU, 2GB RAM
  - Frontend - 1 vCPU, 1GB RAM

### Configuration Options

```bash
# Project ID
export GCP_PROJECT_ID="your-project-id"

# Region (us-central1, us-east1, europe-west1, etc.)
export GCP_REGION="us-central1"

# Service Name
export AIM_SERVICE_NAME="aim"

# Cloud SQL Instance Name
export AIM_SQL_INSTANCE="aim-postgres-123456"

# Redis Instance Name
export AIM_REDIS_INSTANCE="aim-redis"

# VPC Connector Name
export AIM_VPC_CONNECTOR="aim-vpc-connector"
```

### Post-Deployment

```bash
# View deployed services
gcloud run services list --region $GCP_REGION

# View backend logs
gcloud run services logs read aim-backend --region $GCP_REGION --limit 100

# Scale backend
gcloud run services update aim-backend \
  --region $GCP_REGION \
  --min-instances 2 \
  --max-instances 10

# Update backend image
gcloud run deploy aim-backend \
  --image ${GCP_REGION}-docker.pkg.dev/${GCP_PROJECT_ID}/aim-docker/aim-backend:latest \
  --region $GCP_REGION
```

### Custom Domain (Optional)

```bash
# Map custom domain
gcloud run domain-mappings create \
  --service aim-frontend \
  --domain yourdomain.com \
  --region $GCP_REGION

# Verify domain ownership in Google Search Console
# https://search.google.com/search-console
```

### Cleanup

```bash
# Delete Cloud Run services
gcloud run services delete aim-backend --region $GCP_REGION --quiet
gcloud run services delete aim-frontend --region $GCP_REGION --quiet

# Delete Cloud SQL instance
gcloud sql instances delete $AIM_SQL_INSTANCE --quiet

# Delete Redis instance
gcloud redis instances delete $AIM_REDIS_INSTANCE --region $GCP_REGION --quiet

# Delete VPC connector
gcloud compute networks vpc-access connectors delete $AIM_VPC_CONNECTOR --region $GCP_REGION --quiet

# Delete Artifact Registry
gcloud artifacts repositories delete aim-docker --location $GCP_REGION --quiet
```

---

## 🟠 AWS Deployment

### Prerequisites

```bash
# Install AWS CLI
# macOS
brew install awscli

# Linux
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

# Windows
# Download from https://aws.amazon.com/cli/

# Configure AWS credentials
aws configure

# Install jq (required for JSON parsing)
# macOS
brew install jq

# Linux
sudo apt-get install jq
```

### Quick Deploy

```bash
# Set environment variables (optional)
export AWS_REGION="us-east-1"

# Run deployment
cd infrastructure/aws
./deploy.sh
```

### What Gets Deployed

- **ECS Fargate Cluster**: Serverless containers
- **ECR Repositories**: Private Docker registries
- **RDS PostgreSQL**: Managed database (20GB storage)
- **ElastiCache Redis**: In-memory cache
- **VPC**: Isolated network (4 subnets across 2 AZs)
- **2 ECS Services**:
  - Backend - 1 vCPU, 2GB RAM
  - Frontend - 0.5 vCPU, 1GB RAM

### Configuration Options

```bash
# AWS Region
export AWS_REGION="us-east-1"

# ECS Cluster Name
export AIM_CLUSTER="aim-cluster"

# Service Name
export AIM_SERVICE="aim"

# ECR Repository Names
export AIM_ECR_BACKEND="aim-backend"
export AIM_ECR_FRONTEND="aim-frontend"

# RDS Instance Identifier
export AIM_RDS_INSTANCE="aim-postgres"

# Redis Cluster ID
export AIM_REDIS="aim-redis"

# VPC Name
export AIM_VPC="aim-vpc"
```

### Post-Deployment

```bash
# View ECS services
aws ecs list-services --cluster $AIM_CLUSTER

# View backend logs
aws logs tail /ecs/aim-backend --follow

# Scale backend
aws ecs update-service \
  --cluster $AIM_CLUSTER \
  --service aim-backend \
  --desired-count 2

# Update backend (force new deployment)
aws ecs update-service \
  --cluster $AIM_CLUSTER \
  --service aim-backend \
  --force-new-deployment
```

### Application Load Balancer (Recommended)

For production, add an Application Load Balancer (ALB):

```bash
# Create ALB
aws elbv2 create-load-balancer \
  --name aim-alb \
  --subnets subnet-xxx subnet-yyy \
  --security-groups sg-xxx

# Create target group
aws elbv2 create-target-group \
  --name aim-backend-tg \
  --protocol HTTP \
  --port 8080 \
  --vpc-id vpc-xxx \
  --target-type ip

# Update ECS service to use ALB
aws ecs update-service \
  --cluster $AIM_CLUSTER \
  --service aim-backend \
  --load-balancers targetGroupArn=arn:aws:elasticloadbalancing:...
```

### Custom Domain (Optional)

```bash
# Create Route53 hosted zone (if needed)
aws route53 create-hosted-zone --name yourdomain.com

# Create A record pointing to ALB
aws route53 change-resource-record-sets \
  --hosted-zone-id Z1234567890ABC \
  --change-batch file://route53-change.json
```

### Cleanup

```bash
# Delete ECS services
aws ecs delete-service --cluster $AIM_CLUSTER --service aim-backend --force
aws ecs delete-service --cluster $AIM_CLUSTER --service aim-frontend --force

# Delete ECS cluster
aws ecs delete-cluster --cluster $AIM_CLUSTER

# Delete RDS instance
aws rds delete-db-instance \
  --db-instance-identifier $AIM_RDS_INSTANCE \
  --skip-final-snapshot

# Delete Redis cluster
aws elasticache delete-cache-cluster --cache-cluster-id $AIM_REDIS

# Delete VPC (requires deleting all resources first)
# This is complex - consider using the AWS console
```

---

## 💰 Cost Comparison

### Monthly Costs (Estimated)

#### Azure Container Apps

| Resource | Configuration | Monthly Cost |
|----------|---------------|--------------|
| Backend Container App | 1 vCPU, 2GB RAM | ~$30 |
| Frontend Container App | 0.5 vCPU, 1GB RAM | ~$15 |
| PostgreSQL Flexible | Burstable, 32GB | ~$20 |
| Redis Cache | Basic, C0 | ~$16 |
| Container Registry | Basic | ~$5 |
| **Total** | | **~$86/month** |

#### Google Cloud Run

| Resource | Configuration | Monthly Cost |
|----------|---------------|--------------|
| Backend Cloud Run | 1 vCPU, 2GB RAM | ~$25 |
| Frontend Cloud Run | 1 vCPU, 1GB RAM | ~$12 |
| Cloud SQL (PostgreSQL) | db-f1-micro | ~$25 |
| Memorystore (Redis) | Basic, 1GB | ~$20 |
| Artifact Registry | | ~$0.10/GB |
| **Total** | | **~$82/month** |

#### AWS ECS Fargate

| Resource | Configuration | Monthly Cost |
|----------|---------------|--------------|
| Backend ECS Task | 1 vCPU, 2GB RAM | ~$35 |
| Frontend ECS Task | 0.5 vCPU, 1GB RAM | ~$18 |
| RDS PostgreSQL | db.t3.micro | ~$30 |
| ElastiCache Redis | cache.t3.micro | ~$25 |
| ECR Storage | | ~$1/GB |
| Data Transfer | | ~$10 |
| **Total** | | **~$119/month** |

**Note**: Costs vary based on region, usage, and data transfer. Always use official cloud pricing calculators.

---

## ⚡ Performance Comparison

### Cold Start Times

| Provider | Cold Start | Warm Start |
|----------|------------|------------|
| **Azure Container Apps** | 2-3 seconds | <100ms |
| **Google Cloud Run** | 1-2 seconds | <100ms |
| **AWS ECS Fargate** | 30-60 seconds | <100ms |

### Throughput (Requests/Second)

| Provider | Single Instance | Auto-Scaled (10 instances) |
|----------|-----------------|----------------------------|
| **Azure Container Apps** | ~500 req/s | ~5,000 req/s |
| **Google Cloud Run** | ~600 req/s | ~6,000 req/s |
| **AWS ECS Fargate** | ~400 req/s | ~4,000 req/s |

### Latency (p95)

| Provider | Database Query | API Response |
|----------|----------------|--------------|
| **Azure Container Apps** | 15-20ms | 50-80ms |
| **Google Cloud Run** | 10-15ms | 40-70ms |
| **AWS ECS Fargate** | 20-25ms | 60-90ms |

---

## 🎯 Recommendations

### Choose **Azure** if:
- ✅ You need fast deployment and auto-scaling
- ✅ You're already using Microsoft services
- ✅ You want integrated monitoring with Application Insights

### Choose **GCP** if:
- ✅ You want the fastest cold starts
- ✅ You need best-in-class serverless experience
- ✅ You want pay-per-use pricing (can be cheaper at low scale)

### Choose **AWS** if:
- ✅ You're already invested in AWS ecosystem
- ✅ You need maximum control and customization
- ✅ You want the most mature container orchestration

---

## 🔒 Security Checklist

Before going to production on any cloud:

- [ ] Enable HTTPS/TLS with managed certificates
- [ ] Configure OAuth providers (Google, Microsoft, Okta)
- [ ] Enable database encryption at rest
- [ ] Set up VPC/Private networking
- [ ] Configure firewall rules (allow only necessary ports)
- [ ] Enable audit logging
- [ ] Set up CloudWatch/Cloud Monitoring alerts
- [ ] Rotate secrets regularly
- [ ] Enable DDoS protection
- [ ] Set up WAF (Web Application Firewall)
- [ ] Configure backup retention policies
- [ ] Enable multi-factor authentication
- [ ] Review IAM permissions (principle of least privilege)

---

## 📞 Support

- **Documentation**: https://opena2a.org/docs
- **GitHub Issues**: https://github.com/opena2a/agent-identity-management/issues
- **Discord**: https://discord.gg/opena2a
- **Email**: info@opena2a.org

---

**🛡️ Happy Cloud Deploying with AIM!**
