@polymorphism-tech/morph-spec 1.0.4 → 2.0.0

package/content/.azure/docs/azure-devops-setup.md

@@ -0,0 +1,454 @@
+# Azure DevOps Setup - Workload Identity Federation
+
+> **MORPH-SPEC Framework**
+> Configuração de CI/CD com autenticação moderna (sem secrets)
+
+---
+
+## 📋 Índice
+
+1. [Pré-requisitos](#pré-requisitos)
+2. [Configurar Workload Identity Federation](#configurar-workload-identity-federation)
+3. [Criar Service Connections](#criar-service-connections)
+4. [Configurar Pipelines](#configurar-pipelines)
+5. [Configurar Environments e Aprovações](#configurar-environments-e-aprovações)
+6. [Troubleshooting](#troubleshooting)
+
+---
+
+## 🔑 Pré-requisitos
+
+### Azure
+- ✅ Subscription Azure ativa
+- ✅ Permissões de Owner ou User Access Administrator na subscription
+- ✅ Azure CLI instalado: https://aka.ms/azure-cli
+
+### Azure DevOps
+- ✅ Organização Azure DevOps criada
+- ✅ Projeto criado
+- ✅ Permissões de administrador do projeto
+
+###Informações Necessárias
+```bash
+# Azure
+SUBSCRIPTION_ID="<sua-subscription-id>"
+TENANT_ID="<seu-tenant-id>"
+
+# Azure DevOps
+ADO_ORG="<sua-org>"          # Ex: polymorphismtech
+ADO_PROJECT="<seu-projeto>"   # Ex: morph-app
+
+# Application
+APP_NAME="<nome-da-app>"      # Ex: myapp
+```
+
+---
+
+## 🌐 Configurar Workload Identity Federation
+
+### Passo 1: Criar App Registration
+
+```bash
+# Login no Azure
+az login
+az account set --subscription $SUBSCRIPTION_ID
+
+# Criar App Registration para Dev
+APP_DEV_NAME="${APP_NAME}-dev-pipeline"
+APP_DEV_ID=$(az ad app create \
+  --display-name "$APP_DEV_NAME" \
+  --query appId -o tsv)
+
+echo "Dev App ID: $APP_DEV_ID"
+
+# Criar Service Principal
+SP_DEV_ID=$(az ad sp create \
+  --id $APP_DEV_ID \
+  --query id -o tsv)
+
+echo "Dev Service Principal ID: $SP_DEV_ID"
+
+# Repetir para Staging e Prod
+APP_STAGING_NAME="${APP_NAME}-staging-pipeline"
+APP_STAGING_ID=$(az ad app create --display-name "$APP_STAGING_NAME" --query appId -o tsv)
+SP_STAGING_ID=$(az ad sp create --id $APP_STAGING_ID --query id -o tsv)
+
+APP_PROD_NAME="${APP_NAME}-prod-pipeline"
+APP_PROD_ID=$(az ad app create --display-name "$APP_PROD_NAME" --query appId -o tsv)
+SP_PROD_ID=$(az ad sp create --id $APP_PROD_ID --query id -o tsv)
+```
+
+### Passo 2: Configurar Federated Credentials
+
+```bash
+# DEV Environment
+cat <<EOF > federated-credential-dev.json
+{
+  "name": "dev-pipeline-federated",
+  "issuer": "https://vstoken.dev.azure.com/<ADO_ORG_ID>",
+  "subject": "sc://$ADO_ORG/$ADO_PROJECT/Azure-Dev-Connection",
+  "description": "Federated credential for dev pipeline",
+  "audiences": [
+    "api://AzureADTokenExchange"
+  ]
+}
+EOF
+
+az ad app federated-credential create \
+  --id $APP_DEV_ID \
+  --parameters federated-credential-dev.json
+
+# STAGING Environment
+cat <<EOF > federated-credential-staging.json
+{
+  "name": "staging-pipeline-federated",
+  "issuer": "https://vstoken.dev.azure.com/<ADO_ORG_ID>",
+  "subject": "sc://$ADO_ORG/$ADO_PROJECT/Azure-Staging-Connection",
+  "description": "Federated credential for staging pipeline",
+  "audiences": [
+    "api://AzureADTokenExchange"
+  ]
+}
+EOF
+
+az ad app federated-credential create \
+  --id $APP_STAGING_ID \
+  --parameters federated-credential-staging.json
+
+# PROD Environment
+cat <<EOF > federated-credential-prod.json
+{
+  "name": "prod-pipeline-federated",
+  "issuer": "https://vstoken.dev.azure.com/<ADO_ORG_ID>",
+  "subject": "sc://$ADO_ORG/$ADO_PROJECT/Azure-Prod-Connection",
+  "description": "Federated credential for prod pipeline",
+  "audiences": [
+    "api://AzureADTokenExchange"
+  ]
+}
+EOF
+
+az ad app federated-credential create \
+  --id $APP_PROD_ID \
+  --parameters federated-credential-prod.json
+```
+
+**📌 Como obter ADO_ORG_ID:**
+```bash
+# Via Azure DevOps UI
+# Vá em: Organization Settings → Overview → Organization ID
+# Ou via API:
+curl -u ":${AZURE_DEVOPS_PAT}" \
+  "https://dev.azure.com/${ADO_ORG}/_apis/connectionData"
+```
+
+### Passo 3: Atribuir Permissões Azure
+
+```bash
+# DEV - Contributor na resource group
+RG_DEV="rg-${APP_NAME}-dev"
+az role assignment create \
+  --assignee $SP_DEV_ID \
+  --role Contributor \
+  --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RG_DEV"
+
+# STAGING - Contributor na resource group
+RG_STAGING="rg-${APP_NAME}-staging"
+az role assignment create \
+  --assignee $SP_STAGING_ID \
+  --role Contributor \
+  --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RG_STAGING"
+
+# PROD - Contributor na resource group
+RG_PROD="rg-${APP_NAME}-prod"
+az role assignment create \
+  --assignee $SP_PROD_ID \
+  --role Contributor \
+  --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RG_PROD"
+
+# ACR - AcrPush para todos
+ACR_ID="/subscriptions/$SUBSCRIPTION_ID/resourceGroups/<rg-acr>/providers/Microsoft.ContainerRegistry/registries/<acr-name>"
+
+az role assignment create --assignee $SP_DEV_ID --role AcrPush --scope $ACR_ID
+az role assignment create --assignee $SP_STAGING_ID --role AcrPush --scope $ACR_ID
+az role assignment create --assignee $SP_PROD_ID --role AcrPush --scope $ACR_ID
+```
+
+---
+
+## 🔗 Criar Service Connections
+
+### Via Azure DevOps UI
+
+#### 1. Service Connection para Azure (Dev)
+
+1. Vá em: **Project Settings** → **Service connections** → **New service connection**
+2. Selecione: **Azure Resource Manager**
+3. Authentication method: **Workload Identity federation (automatic)**
+4. Scope level: **Subscription**
+5. Preencha:
+   - **Subscription ID**: `<sua-subscription-id>`
+   - **Service connection name**: `Azure-Dev-Connection`
+   - **Service Principal ID**: `$APP_DEV_ID` (do Passo 1)
+6. Marque: **Grant access permission to all pipelines** (ou configure por pipeline)
+7. Click: **Save**
+
+#### 2. Repetir para Staging e Prod
+
+- **Staging**: Nome `Azure-Staging-Connection`, usar `$APP_STAGING_ID`
+- **Prod**: Nome `Azure-Prod-Connection`, usar `$APP_PROD_ID`
+
+#### 3. Service Connection para ACR
+
+1. **New service connection** → **Docker Registry**
+2. Registry type: **Azure Container Registry**
+3. Authentication type: **Workload Identity federation**
+4. Preencha:
+   - **Azure subscription**: Selecione a subscription
+   - **Azure container registry**: Selecione seu ACR
+   - **Service connection name**: `ACR-Connection`
+5. **Save**
+
+### Via Azure CLI (Alternativa)
+
+```bash
+# Requer Azure DevOps extension
+az extension add --name azure-devops
+
+# Login
+az devops configure --defaults organization=https://dev.azure.com/$ADO_ORG project=$ADO_PROJECT
+
+# Criar service connection (exemplo simplificado)
+# Nota: Workload Identity via CLI é complexo, recomenda-se usar UI
+```
+
+---
+
+## ⚙️ Configurar Pipelines
+
+### Passo 1: Importar Pipelines
+
+1. Vá em: **Pipelines** → **New pipeline**
+2. Selecione: **Azure Repos Git** (ou seu SCM)
+3. Selecione seu repositório
+4. **Existing Azure Pipelines YAML file**
+5. Path: `.azure/pipelines/dev-pipeline.yml`
+6. **Continue** → **Save** (não run ainda)
+
+Repetir para:
+- `.azure/pipelines/staging-pipeline.yml`
+- `.azure/pipelines/prod-pipeline.yml`
+
+### Passo 2: Configurar Variáveis
+
+#### Variáveis no Pipeline Level
+
+Para cada pipeline, adicione as variáveis:
+
+**Dev Pipeline** → **Edit** → **Variables**:
+```
+ACR_NAME: <seu-acr-name>
+APP_NAME: <seu-app-name>
+SUBSCRIPTION_ID: <subscription-id>
+```
+
+**Staging Pipeline** - mesmas variáveis
+
+**Prod Pipeline** - mesmas variáveis
+
+#### Variáveis no Group Level (Opcional)
+
+1. **Pipelines** → **Library** → **+ Variable group**
+2. Nome: `morph-common-vars`
+3. Adicionar:
+   ```
+   ACR_NAME: <seu-acr>
+   APP_NAME: <seu-app>
+   SUBSCRIPTION_ID: <subscription-id>
+   ```
+4. Linkar aos pipelines:
+   ```yaml
+   variables:
+     - group: morph-common-vars
+     - template: pipeline-variables.yml
+   ```
+
+---
+
+## 🛡️ Configurar Environments e Aprovações
+
+### Passo 1: Criar Environments
+
+1. **Pipelines** → **Environments** → **New environment**
+2. Criar 3 environments:
+
+**Dev Environment:**
+- Name: `dev`
+- Resource: None
+- Approvals: **Nenhuma** (deploy automático)
+
+**Staging Environment:**
+- Name: `staging`
+- Resource: None
+- Approvals: **Opcional** (recomendado nenhuma para deploy rápido)
+  - Se desejar: Add approver selecione você mesmo
+  - Timeout: 24 hours
+
+**Production Environment:**
+- Name: `production`
+- Resource: None
+- Approvals: **OBRIGATÓRIO**
+  - Add approvers: Selecione você mesmo
+  - Timeout: 48 hours
+  - **Checks**: Adicionar "Invoke REST API" para verificações adicionais (opcional)
+
+### Passo 2: Configurar Branch Policies (Opcional)
+
+Para `main` branch:
+
+1. **Repos** → **Branches** → `main` → **Branch policies**
+2. Habilitar:
+   - **Require a minimum number of reviewers**: 0 (self-review via approval gate)
+   - **Check for linked work items**: Recommended
+   - **Build validation**: Link prod pipeline
+
+---
+
+## 🧪 Testar Configuração
+
+### Teste 1: Dev Pipeline
+
+```bash
+# Criar branch develop
+git checkout -b develop
+git push origin develop
+
+# Fazer um commit qualquer
+echo "test" > test.txt
+git add test.txt
+git commit -m "test: trigger dev pipeline"
+git push origin develop
+```
+
+**Verificar:**
+- Pipeline triggou automaticamente
+- Build passou
+- Deploy para App Service Free foi bem-sucedido
+- Health check passou
+
+### Teste 2: Staging Pipeline
+
+```bash
+# Merge develop em main
+git checkout main
+git merge develop
+git push origin main
+```
+
+**Verificar:**
+- Staging pipeline triggou
+- Container foi buildado e pushed para ACR
+- Deploy para Container Apps funcionou
+- Integration tests passaram
+
+### Teste 3: Prod Pipeline (Manual)
+
+1. **Pipelines** → **prod-pipeline** → **Run pipeline**
+2. Verificar aprovação manual aparece
+3. Aprovar deploy
+4. Verificar deployment bem-sucedido
+
+---
+
+## 🆘 Troubleshooting
+
+### Erro: "Failed to get federated token"
+
+**Causa:** Subject no federated credential não match com service connection.
+
+**Solução:**
+```bash
+# Verificar subject correto
+# Deve ser: sc://<ORG>/<PROJECT>/<SERVICE_CONNECTION_NAME>
+
+# Recriar federated credential com subject correto
+az ad app federated-credential delete \
+  --id $APP_ID \
+  --federated-credential-id <credential-id>
+
+# Criar novamente com subject correto
+az ad app federated-credential create \
+  --id $APP_ID \
+  --parameters federated-credential.json
+```
+
+### Erro: "Insufficient permissions"
+
+**Causa:** Service Principal não tem permissões na subscription/resource group.
+
+**Solução:**
+```bash
+# Verificar role assignments
+az role assignment list \
+  --assignee $SP_ID \
+  --output table
+
+# Adicionar Contributor se necessário
+az role assignment create \
+  --assignee $SP_ID \
+  --role Contributor \
+  --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RG_NAME"
+```
+
+### Erro: "Container registry not found"
+
+**Causa:** Service Principal não tem permissão no ACR.
+
+**Solução:**
+```bash
+# Adicionar AcrPush role
+az role assignment create \
+  --assignee $SP_ID \
+  --role AcrPush \
+  --scope $ACR_ID
+```
+
+### Erro: "Pipeline not authorized to access service connection"
+
+**Causa:** Pipeline não foi autorizado a usar a service connection.
+
+**Solução:**
+1. **Project Settings** → **Service connections**
+2. Click na service connection
+3. **Security** → Adicionar pipeline específico ou marcar "Grant access to all pipelines"
+
+---
+
+## 📚 Referências
+
+- [Workload Identity Federation](https://learn.microsoft.com/azure/devops/pipelines/library/connect-to-azure)
+- [Azure Pipelines YAML Schema](https://learn.microsoft.com/azure/devops/pipelines/yaml-schema)
+- [Environments](https://learn.microsoft.com/azure/devops/pipelines/process/environments)
+- [Service Connections](https://learn.microsoft.com/azure/devops/pipelines/library/service-endpoints)
+
+---
+
+## ✅ Checklist Final
+
+Antes de ir para produção:
+
+- [ ] Workload Identity configurada para dev/staging/prod
+- [ ] Service connections criadas e testadas
+- [ ] Variáveis configuradas (ACR_NAME, APP_NAME, SUBSCRIPTION_ID)
+- [ ] Environments criados (dev, staging, production)
+- [ ] Aprovações configuradas (production requer aprovação manual)
+- [ ] Dev pipeline testado com sucesso
+- [ ] Staging pipeline testado com sucesso
+- [ ] Prod pipeline testado com aprovação
+- [ ] Health checks funcionando
+- [ ] Monitoring configurado (Application Insights)
+- [ ] Rollback plan documentado
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*