@polymorphism-tech/morph-spec 1.0.4 → 2.0.0

package/content/.azure/README.md

@@ -0,0 +1,293 @@
+# MORPH-SPEC - Azure DevOps Pipelines
+
+> **CI/CD para One-Person Business com Workload Identity Federation (sem secrets)**
+
+---
+
+## 🚀 Quick Start
+
+### 1. Configurar Workload Identity (10 min)
+
+```bash
+# Ver guia completo em: docs/azure-devops-setup.md
+
+# Criar App Registrations
+az ad app create --display-name "myapp-staging-pipeline"
+az ad app create --display-name "myapp-prod-pipeline"
+
+# Configurar federated credentials
+# (Ver guia detalhado)
+```
+
+### 2. Importar Pipelines no Azure DevOps
+
+1. **Pipelines** → **New pipeline**
+2. **Azure Repos Git** → Selecione repo
+3. **Existing Azure Pipelines YAML file**
+4. Selecione:
+   - `.azure/pipelines/staging-pipeline.yml`
+   - `.azure/pipelines/prod-pipeline.yml`
+
+### 3. Configurar Variáveis
+
+Para cada pipeline, adicione:
+```
+ACR_NAME: <seu-acr-name>
+APP_NAME: <seu-app-name>
+SUBSCRIPTION_ID: <subscription-id>
+```
+
+### 4. Criar Environments
+
+1. **Pipelines** → **Environments** → **New environment**
+2. Criar:
+   - `staging` (sem aprovação - deploy rápido)
+   - `production` (aprovação obrigatória)
+
+### 5. Testar!
+
+```bash
+# Trigger staging pipeline
+git checkout staging
+git commit -m "test" --allow-empty
+git push origin staging
+
+# Trigger prod pipeline
+git checkout main
+git commit -m "test" --allow-empty
+git push origin main
+# ⏸️ Aprovar manualmente no Azure DevOps
+```
+
+---
+
+## 📁 Estrutura
+
+```
+.azure/
+├── README.md                           # Este arquivo
+├── docs/
+│   ├── azure-devops-setup.md          # Guia completo de setup
+│   ├── local-development.md           # Como rodar projeto local
+│   └── branch-strategy.md             # Estratégia de branches
+└── pipelines/
+    ├── staging-pipeline.yml           # Pipeline staging (branch: staging)
+    ├── prod-pipeline.yml              # Pipeline prod (branch: main/master)
+    ├── pipeline-variables.yml         # Variáveis compartilhadas
+    └── templates/
+        ├── build-dotnet.yml           # Template: Build .NET
+        ├── deploy-app-service.yml     # Template: Deploy App Service
+        ├── deploy-container-app.yml   # Template: Deploy Container Apps
+        └── infra-deploy.yml           # Template: Deploy Bicep
+```
+
+---
+
+## 🔄 Pipelines
+
+### Staging Pipeline (`staging-pipeline.yml`)
+
+**Hosting:** Container Apps com scale-to-zero (~$5-10/mês)
+
+**Trigger:** Push em `staging` branch
+
+**Stages:**
+1. ✅ Build & Test
+2. ✅ Deploy Infrastructure (Bicep)
+3. ✅ Build Container Image
+4. ✅ Push to ACR
+5. ✅ Deploy Container App
+6. ✅ Integration Tests
+
+**Aprovação:** Nenhuma (deploy automático)
+
+**Uso:** QA, testes de integração
+
+---
+
+### Prod Pipeline (`prod-pipeline.yml`)
+
+**Hosting:** Container Apps always-on (~$10-20/mês)
+
+**Trigger:** Push em `main` ou `master` branch
+
+**Stages:**
+1. ✅ Build & Test
+2. ✅ Security Scan
+3. ✅ Deploy Infrastructure (Bicep)  ← **Approval Required**
+4. ✅ Build Container Image
+5. ✅ Security Scan (Image)
+6. ✅ Deploy to Production  ← **Approval Required**
+7. ✅ Smoke Tests (Critical)
+8. ✅ Monitor & Report
+
+**Aprovação:** OBRIGATÓRIA (manual approval gate)
+
+**Uso:** Produção, ambiente crítico
+
+---
+
+## 🌐 Desenvolvimento Local
+
+**Developers NÃO têm ambiente próprio.** Ao invés disso:
+
+- ✅ Rodam projeto **LOCAL** (Visual Studio/Rider/VS Code)
+- ✅ Acessam recursos **REMOTOS** staging (SQL, Storage, Key Vault)
+- ✅ Testam localmente antes de commitar
+
+**Ver guia completo:** [`docs/local-development.md`](docs/local-development.md)
+
+---
+
+## 🎯 Fluxo Completo
+
+### Desenvolvimento Diário
+
+```bash
+# 1. Criar feature branch
+git checkout staging
+git pull origin staging
+git checkout -b feature/nova-funcionalidade
+
+# 2. Desenvolver LOCAL
+dotnet run  # Conecta em recursos staging
+
+# 3. Commitar
+git add .
+git commit -m "feat: adiciona nova funcionalidade"
+git push origin feature/nova-funcionalidade
+
+# 4. Criar PR para staging
+# Azure DevOps → Repos → Pull Requests → New
+# Source: feature/nova-funcionalidade → Target: staging
+# Self-approve e merge
+
+# 5. Staging pipeline triggado automaticamente
+# ✅ Deploy para staging
+```
+
+### Release para Produção
+
+```bash
+# 1. Criar PR staging → main
+# Azure DevOps → Repos → Pull Requests → New
+# Source: staging → Target: main
+
+# 2. Self-review e merge
+
+# 3. Prod pipeline triggado
+# ⏸️ Approval gate aparece
+# Revisar deployment summary
+# Aprovar manualmente
+
+# 4. Deploy para produção
+# ✅ Aplicação em produção
+```
+
+---
+
+## 📊 Comparativo de Ambientes
+
+| Aspecto | Staging | Prod |
+|---------|---------|------|
+| **Hosting** | Container Apps | Container Apps |
+| **Custo** | $5-10/mês | $10-20/mês |
+| **Disponibilidade** | Scale-to-zero | Always-on (min 1) |
+| **SSL** | Custom domain OK | Custom domain OK |
+| **Auto-scaling** | ✅ Sim | ✅ Sim |
+| **Trigger** | Push to `staging` | Push to `main` |
+| **Aprovação** | Nenhuma | **Obrigatória** |
+| **Tests** | Unit + Integration | Unit + Integration + Security |
+
+---
+
+## 🔐 Workload Identity Federation
+
+### O que é?
+
+Autenticação moderna do Azure DevOps para Azure **sem usar secrets/passwords**.
+
+### Vantagens
+
+| Tradicional (Service Principal) | Workload Identity |
+|--------------------------------|-------------------|
+| ❌ Secrets expiram (1-2 anos) | ✅ Token auto-renova |
+| ❌ Secrets vazam facilmente | ✅ Sem secrets armazenados |
+| ❌ Rotação manual | ✅ Rotação automática |
+| ❌ Dificil auditar | ✅ Audit trail completo |
+
+### Setup
+
+Ver guia completo: [`docs/azure-devops-setup.md`](docs/azure-devops-setup.md)
+
+---
+
+## 🆘 Troubleshooting
+
+### Pipeline falha com "Failed to get federated token"
+
+**Causa:** Federated credential não configurado corretamente.
+
+**Solução:**
+1. Verificar subject do federated credential
+2. Deve ser: `sc://<ORG>/<PROJECT>/<SERVICE_CONNECTION_NAME>`
+3. Recriar se necessário (ver `docs/azure-devops-setup.md`)
+
+### Pipeline falha com "Insufficient permissions"
+
+**Causa:** Service Principal não tem permissões.
+
+**Solução:**
+```bash
+# Adicionar Contributor role
+az role assignment create \
+  --assignee <SP_ID> \
+  --role Contributor \
+  --scope "/subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>"
+```
+
+### Container não sobe após deploy
+
+**Causa:** Possíveis: imagem incorreta, health check falhando, ACR permissions.
+
+**Solução:**
+```bash
+# Ver logs do Container App
+az containerapp logs show \
+  -n ca-myapp-staging \
+  -g rg-myapp-staging \
+  --follow
+```
+
+---
+
+## 📚 Documentação Completa
+
+| Documento | Descrição |
+|-----------|-----------|
+| [Azure DevOps Setup](docs/azure-devops-setup.md) | Setup completo (Workload Identity, Service Connections, Environments) |
+| [Local Development](docs/local-development.md) | Como rodar projeto local e acessar recursos staging |
+| [Branch Strategy](docs/branch-strategy.md) | Estratégia de branches (staging/main, feature branches) |
+| [Migration Guide](../content/.morph/standards/migration-guide.md) | App Service → Container Apps + CI/CD |
+| [Azure Standards](../content/.morph/standards/azure.md) | Padrões Azure e IaC |
+
+---
+
+## ✅ Checklist de Produção
+
+Antes de ir para produção:
+
+- [ ] Workload Identity configurada (staging/prod)
+- [ ] Service connections criadas e testadas
+- [ ] Variáveis configuradas (ACR_NAME, APP_NAME, SUBSCRIPTION_ID)
+- [ ] Environments criados (staging sem aprovação, prod com aprovação)
+- [ ] Staging pipeline testado com sucesso
+- [ ] Prod pipeline testado com aprovação
+- [ ] Health checks implementados e funcionando
+- [ ] Application Insights configurado
+- [ ] Alerts configurados (CPU, Memory, Availability)
+- [ ] Runbook de rollback documentado
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*