@polymorphism-tech/morph-spec 4.10.9 → 4.11.0

package/framework/templates/infrastructure/azure/README.md

@@ -1,286 +1,286 @@
-# MORPH-SPEC - Templates Bicep
-
-Templates de infraestrutura para Azure com suporte a App Service e Container Apps.
-
----
-
-## 🚀 Quick Start
-
-### 1. App Service Free (Desenvolvimento - $0/mês)
-
-```bash
-# Deploy infraestrutura com App Service Free
-az deployment group create \
-  --resource-group rg-myapp-dev \
-  --template-file main.bicep \
-  --parameters @parameters.dev.json \
-  --parameters appName=myapp
-```
-
-### 2. Container Apps (Produção - $5-15/mês)
-
-```bash
-# Build e push imagem para ACR
-az acr build \
-  --registry acrXXXX \
-  --image myapp:v1.0.0 \
-  --file Dockerfile \
-  .
-
-# Deploy infraestrutura com Container Apps
-az deployment group create \
-  --resource-group rg-myapp-prod \
-  --template-file main.bicep \
-  --parameters @parameters.prod.json \
-  --parameters appName=myapp
-```
-
----
-
-## 📁 Estrutura de Arquivos
-
-```
-infra/
-├── main.bicep                    # Entry point com lógica condicional
-├── parameters.dev.json           # Params dev (App Service Free)
-├── parameters.prod.json          # Params prod (Container Apps)
-├── app-service.bicep             # Template App Service
-├── container-app.bicep           # Template Container App
-├── container-app-env.bicep       # Container Apps Environment
-├── sql-database.bicep            # Azure SQL Database
-├── storage.bicep                 # Storage Account
-├── key-vault.bicep               # Key Vault
-└── app-insights.bicep            # Application Insights
-```
-
----
-
-## ⚙️ Parâmetros Principais
-
-### main.bicep
-
-| Parâmetro | Tipo | Default | Descrição |
-|-----------|------|---------|-----------|
-| `environment` | string | `dev` | Ambiente (dev, staging, prod) |
-| `appName` | string | **required** | Nome da aplicação (3-15 chars) |
-| `location` | string | `resourceGroup().location` | Região Azure |
-| `hostingType` | string | `appservice` | Tipo de hosting (`appservice` ou `containerapp`) |
-| `appServiceSku` | string | `F1` | SKU do App Service (F1, B1, S1, P1v2) |
-| `containerImage` | string | `mcr.microsoft.com/hello-world:latest` | Imagem Docker (apenas Container Apps) |
-| `sqlAdminPassword` | securestring | **required** | Senha do SQL Server |
-
----
-
-## 🌐 Escolhendo o Hosting Type
-
-### App Service (`hostingType: appservice`)
-
-**Usar quando:**
-- ✅ Orçamento zero (Free F1)
-- ✅ MVP ou protótipo
-- ✅ Tráfego baixo (<100 req/dia)
-- ✅ App tolerante a cold starts (20 min sleep)
-- ✅ Deploy simplificado (sem Docker)
-
-**SKUs disponíveis:**
-- `F1` (Free): $0/mês - 1GB RAM, 60 min CPU/dia, sleep após 20min
-- `B1` (Basic): $13/mês - 1.75GB RAM, always-on
-- `S1` (Standard): $70/mês - 1.75GB RAM, auto-scale, slots
-- `P1v2` (Premium): $85/mês - 3.5GB RAM, melhor performance
-
-### Container Apps (`hostingType: containerapp`)
-
-**Usar quando:**
-- ✅ Produção com SLA 24/7
-- ✅ Auto-scaling baseado em demanda
-- ✅ SSL customizado necessário
-- ✅ Background jobs (Hangfire)
-- ✅ Arquitetura microserviços
-
-**Custo:** $0-15/mês (scale-to-zero + consumo)
-
----
-
-## 📝 Configuração por Ambiente
-
-### Development (parameters.dev.json)
-
-```json
-{
-  "environment": { "value": "dev" },
-  "hostingType": { "value": "appservice" },
-  "appServiceSku": { "value": "F1" }
-}
-```
-
-**Infraestrutura:**
-- App Service Free F1
-- Azure SQL Free (32GB)
-- App Insights Free (5GB)
-
-**Custo total:** $0/mês
-
-### Staging (parameters.staging.json)
-
-```json
-{
-  "environment": { "value": "staging" },
-  "hostingType": { "value": "containerapp" },
-  "minReplicas": { "value": 0 }  // scale-to-zero
-}
-```
-
-**Infraestrutura:**
-- Container Apps (scale-to-zero)
-- Azure SQL Free (32GB)
-- ACR Basic
-- App Insights Free
-
-**Custo total:** $5-10/mês
-
-### Production (parameters.prod.json)
-
-```json
-{
-  "environment": { "value": "prod" },
-  "hostingType": { "value": "containerapp" },
-  "minReplicas": { "value": 1 }  // always-on
-}
-```
-
-**Infraestrutura:**
-- Container Apps (min 1 replica)
-- Azure SQL Free (ou pago se necessário)
-- ACR Basic
-- App Insights (pode ultrapassar free tier)
-
-**Custo total:** $10-20/mês
-
----
-
-## 🔧 Customização
-
-### Adicionar variáveis de ambiente
-
-**App Service:**
-```bicep
-module appService 'app-service.bicep' = {
-  params: {
-    envVars: {
-      MY_CUSTOM_VAR: 'value'
-      ANOTHER_VAR: 'another-value'
-    }
-  }
-}
-```
-
-**Container Apps:**
-```bicep
-module containerApp 'container-app.bicep' = {
-  params: {
-    envVars: [
-      {
-        name: 'MY_CUSTOM_VAR'
-        value: 'value'
-      }
-    ]
-  }
-}
-```
-
-### Usar secrets do Key Vault
-
-```bicep
-param sqlAdminPassword string {
-  reference: {
-    keyVault: {
-      id: '/subscriptions/.../providers/Microsoft.KeyVault/vaults/kv-myapp'
-    }
-    secretName: 'sql-admin-password'
-  }
-}
-```
-
----
-
-## 🔄 Migração App Service → Container Apps
-
-Ver guia completo em: `../../standards/migration-guide.md`
-
-**Resumo:**
-1. Criar Dockerfile
-2. Implementar health checks
-3. Build e push para ACR
-4. Atualizar `parameters.json` → `hostingType: containerapp`
-5. Redeploy
-6. Testar
-7. Cutover DNS
-
----
-
-## 📊 Outputs Gerados
-
-Após deploy, os seguintes outputs são gerados:
-
-```bash
-# Obter URL da aplicação
-az deployment group show \
-  -g rg-myapp-dev \
-  -n deployment-name \
-  --query properties.outputs.appUrl.value
-
-# Obter connection string SQL
-az deployment group show \
-  -g rg-myapp-dev \
-  -n deployment-name \
-  --query properties.outputs.sqlConnectionString.value
-
-# Obter App Insights connection string
-az deployment group show \
-  -g rg-myapp-dev \
-  -n deployment-name \
-  --query properties.outputs.appInsightsConnectionString.value
-```
-
----
-
-## 🆘 Troubleshooting
-
-### Erro: "The template deployment 'X' is not valid"
-
-Validar template:
-```bash
-az deployment group validate \
-  --resource-group rg-myapp-dev \
-  --template-file main.bicep \
-  --parameters @parameters.dev.json
-```
-
-### Erro: "SKU not available in this location"
-
-Verificar SKUs disponíveis:
-```bash
-az appservice list-locations --sku F1
-```
-
-### Deploy muito lento
-
-Container Apps pode levar 5-10 minutos no primeiro deploy. Use `--no-wait` para não bloquear:
-```bash
-az deployment group create \
-  ... \
-  --no-wait
-```
-
----
-
-## 📚 Referências
-
-- [Bicep Documentation](https://learn.microsoft.com/azure/azure-resource-manager/bicep/)
-- [App Service Bicep Reference](https://learn.microsoft.com/azure/templates/microsoft.web/sites)
-- [Container Apps Bicep Reference](https://learn.microsoft.com/azure/templates/microsoft.app/containerapps)
-- [Azure CLI Reference](https://learn.microsoft.com/cli/azure/)
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# MORPH-SPEC - Templates Bicep
+
+Templates de infraestrutura para Azure com suporte a App Service e Container Apps.
+
+---
+
+## 🚀 Quick Start
+
+### 1. App Service Free (Desenvolvimento - $0/mês)
+
+```bash
+# Deploy infraestrutura com App Service Free
+az deployment group create \
+  --resource-group rg-myapp-dev \
+  --template-file main.bicep \
+  --parameters @parameters.dev.json \
+  --parameters appName=myapp
+```
+
+### 2. Container Apps (Produção - $5-15/mês)
+
+```bash
+# Build e push imagem para ACR
+az acr build \
+  --registry acrXXXX \
+  --image myapp:v1.0.0 \
+  --file Dockerfile \
+  .
+
+# Deploy infraestrutura com Container Apps
+az deployment group create \
+  --resource-group rg-myapp-prod \
+  --template-file main.bicep \
+  --parameters @parameters.prod.json \
+  --parameters appName=myapp
+```
+
+---
+
+## 📁 Estrutura de Arquivos
+
+```
+infra/
+├── main.bicep                    # Entry point com lógica condicional
+├── parameters.dev.json           # Params dev (App Service Free)
+├── parameters.prod.json          # Params prod (Container Apps)
+├── app-service.bicep             # Template App Service
+├── container-app.bicep           # Template Container App
+├── container-app-env.bicep       # Container Apps Environment
+├── sql-database.bicep            # Azure SQL Database
+├── storage.bicep                 # Storage Account
+├── key-vault.bicep               # Key Vault
+└── app-insights.bicep            # Application Insights
+```
+
+---
+
+## ⚙️ Parâmetros Principais
+
+### main.bicep
+
+| Parâmetro | Tipo | Default | Descrição |
+|-----------|------|---------|-----------|
+| `environment` | string | `dev` | Ambiente (dev, staging, prod) |
+| `appName` | string | **required** | Nome da aplicação (3-15 chars) |
+| `location` | string | `resourceGroup().location` | Região Azure |
+| `hostingType` | string | `appservice` | Tipo de hosting (`appservice` ou `containerapp`) |
+| `appServiceSku` | string | `F1` | SKU do App Service (F1, B1, S1, P1v2) |
+| `containerImage` | string | `mcr.microsoft.com/hello-world:latest` | Imagem Docker (apenas Container Apps) |
+| `sqlAdminPassword` | securestring | **required** | Senha do SQL Server |
+
+---
+
+## 🌐 Escolhendo o Hosting Type
+
+### App Service (`hostingType: appservice`)
+
+**Usar quando:**
+- ✅ Orçamento zero (Free F1)
+- ✅ MVP ou protótipo
+- ✅ Tráfego baixo (<100 req/dia)
+- ✅ App tolerante a cold starts (20 min sleep)
+- ✅ Deploy simplificado (sem Docker)
+
+**SKUs disponíveis:**
+- `F1` (Free): $0/mês - 1GB RAM, 60 min CPU/dia, sleep após 20min
+- `B1` (Basic): $13/mês - 1.75GB RAM, always-on
+- `S1` (Standard): $70/mês - 1.75GB RAM, auto-scale, slots
+- `P1v2` (Premium): $85/mês - 3.5GB RAM, melhor performance
+
+### Container Apps (`hostingType: containerapp`)
+
+**Usar quando:**
+- ✅ Produção com SLA 24/7
+- ✅ Auto-scaling baseado em demanda
+- ✅ SSL customizado necessário
+- ✅ Background jobs (Hangfire)
+- ✅ Arquitetura microserviços
+
+**Custo:** $0-15/mês (scale-to-zero + consumo)
+
+---
+
+## 📝 Configuração por Ambiente
+
+### Development (parameters.dev.json)
+
+```json
+{
+  "environment": { "value": "dev" },
+  "hostingType": { "value": "appservice" },
+  "appServiceSku": { "value": "F1" }
+}
+```
+
+**Infraestrutura:**
+- App Service Free F1
+- Azure SQL Free (32GB)
+- App Insights Free (5GB)
+
+**Custo total:** $0/mês
+
+### Staging (parameters.staging.json)
+
+```json
+{
+  "environment": { "value": "staging" },
+  "hostingType": { "value": "containerapp" },
+  "minReplicas": { "value": 0 }  // scale-to-zero
+}
+```
+
+**Infraestrutura:**
+- Container Apps (scale-to-zero)
+- Azure SQL Free (32GB)
+- ACR Basic
+- App Insights Free
+
+**Custo total:** $5-10/mês
+
+### Production (parameters.prod.json)
+
+```json
+{
+  "environment": { "value": "prod" },
+  "hostingType": { "value": "containerapp" },
+  "minReplicas": { "value": 1 }  // always-on
+}
+```
+
+**Infraestrutura:**
+- Container Apps (min 1 replica)
+- Azure SQL Free (ou pago se necessário)
+- ACR Basic
+- App Insights (pode ultrapassar free tier)
+
+**Custo total:** $10-20/mês
+
+---
+
+## 🔧 Customização
+
+### Adicionar variáveis de ambiente
+
+**App Service:**
+```bicep
+module appService 'app-service.bicep' = {
+  params: {
+    envVars: {
+      MY_CUSTOM_VAR: 'value'
+      ANOTHER_VAR: 'another-value'
+    }
+  }
+}
+```
+
+**Container Apps:**
+```bicep
+module containerApp 'container-app.bicep' = {
+  params: {
+    envVars: [
+      {
+        name: 'MY_CUSTOM_VAR'
+        value: 'value'
+      }
+    ]
+  }
+}
+```
+
+### Usar secrets do Key Vault
+
+```bicep
+param sqlAdminPassword string {
+  reference: {
+    keyVault: {
+      id: '/subscriptions/.../providers/Microsoft.KeyVault/vaults/kv-myapp'
+    }
+    secretName: 'sql-admin-password'
+  }
+}
+```
+
+---
+
+## 🔄 Migração App Service → Container Apps
+
+Ver guia completo em: `../../standards/migration-guide.md`
+
+**Resumo:**
+1. Criar Dockerfile
+2. Implementar health checks
+3. Build e push para ACR
+4. Atualizar `parameters.json` → `hostingType: containerapp`
+5. Redeploy
+6. Testar
+7. Cutover DNS
+
+---
+
+## 📊 Outputs Gerados
+
+Após deploy, os seguintes outputs são gerados:
+
+```bash
+# Obter URL da aplicação
+az deployment group show \
+  -g rg-myapp-dev \
+  -n deployment-name \
+  --query properties.outputs.appUrl.value
+
+# Obter connection string SQL
+az deployment group show \
+  -g rg-myapp-dev \
+  -n deployment-name \
+  --query properties.outputs.sqlConnectionString.value
+
+# Obter App Insights connection string
+az deployment group show \
+  -g rg-myapp-dev \
+  -n deployment-name \
+  --query properties.outputs.appInsightsConnectionString.value
+```
+
+---
+
+## 🆘 Troubleshooting
+
+### Erro: "The template deployment 'X' is not valid"
+
+Validar template:
+```bash
+az deployment group validate \
+  --resource-group rg-myapp-dev \
+  --template-file main.bicep \
+  --parameters @parameters.dev.json
+```
+
+### Erro: "SKU not available in this location"
+
+Verificar SKUs disponíveis:
+```bash
+az appservice list-locations --sku F1
+```
+
+### Deploy muito lento
+
+Container Apps pode levar 5-10 minutos no primeiro deploy. Use `--no-wait` para não bloquear:
+```bash
+az deployment group create \
+  ... \
+  --no-wait
+```
+
+---
+
+## 📚 Referências
+
+- [Bicep Documentation](https://learn.microsoft.com/azure/azure-resource-manager/bicep/)
+- [App Service Bicep Reference](https://learn.microsoft.com/azure/templates/microsoft.web/sites)
+- [Container Apps Bicep Reference](https://learn.microsoft.com/azure/templates/microsoft.app/containerapps)
+- [Azure CLI Reference](https://learn.microsoft.com/cli/azure/)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*