Expand FASE 4 documentation and add ArgoCD reminders

CRITICAL: ArgoCD is installed but NOT configured yet Changes: - Expanded FASE 4 in ROADMAP.md with detailed ArgoCD setup steps - Added ArgoCD ApplicationSet configuration for preview environments - Created TODO-ARGOCD.md as explicit reminder file - Added comprehensive checklist for FASE 4 (won't forget!) ArgoCD details: - URL: https://argocd.fuq.tv - Status: Installed, pods running, NOT configured - When: FASE 4 (after Frontend + Agents are done) - Why: Critical for preview environments automation - Time: ~2-3 hours to configure fully TODO-ARGOCD.md will be deleted after completing FASE 4. Co-Authored-By: Claude Sonnet 4.5 (1M context) <noreply@anthropic.com>
2026-01-20 01:26:42 +01:00
parent 59de114c90
commit e15e60c810
2 changed files with 378 additions and 19 deletions
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -241,39 +241,232 @@ kubectl get pods -n control-plane

 ---

-### FASE 4: GitOps y Deployments
+### FASE 4: GitOps y Deployments 🚀
+
+**⚠️ IMPORTANTE**: ArgoCD ya está instalado en el cluster pero NO configurado
+**URL**: https://argocd.fuq.tv
+**Credenciales**: admin / LyPF4Hy0wvp52IoU
+
+---
+
+#### 4.1 ArgoCD Setup (CRÍTICO - No olvidar)
+**Objetivo**: Migrar de kubectl manual a GitOps automático
+**Prioridad**: ALTA - Esto desbloquea todo lo demás
+
+**Estado actual (sin ArgoCD)**:
+```bash
+git push → CI/CD → kubectl apply (MANUAL)
+```
+
+**Estado deseado (con ArgoCD)**:
+```bash
+git push → CI/CD → git push manifests → ArgoCD auto-sync ✨
+```

-#### 4.1 ArgoCD Setup
-**Objetivo**: GitOps funcional
 **Tareas**:
- [ ] Conectar repos de Gitea a ArgoCD
- [ ] Crear Applications
- [ ] Auto-sync configurado
+- [ ] **Login a ArgoCD UI**: https://argocd.fuq.tv (verificar acceso)
+- [ ] **Conectar Gitea repo** al ArgoCD
+  - Agregar repo: `https://git.fuq.tv/admin/aiworker.git`
+  - Configurar credenciales (usar token de Gitea)
+- [ ] **Crear Application para Backend**
+  ```bash
+  argocd app create backend \
+    --repo https://git.fuq.tv/admin/aiworker.git \
+    --path k8s/backend \
+    --dest-server https://kubernetes.default.svc \
+    --dest-namespace control-plane \
+    --sync-policy automated
+  ```
+- [ ] **Crear Application para Frontend**
+  ```bash
+  argocd app create frontend \
+    --repo https://git.fuq.tv/admin/aiworker.git \
+    --path k8s/frontend \
+    --dest-server https://kubernetes.default.svc \
+    --dest-namespace control-plane \
+    --sync-policy automated
+  ```
+- [ ] **Habilitar auto-sync y auto-prune**
+  ```bash
+  argocd app set backend --sync-policy automated --auto-prune --self-heal
+  argocd app set frontend --sync-policy automated --auto-prune --self-heal
+  ```
+- [ ] **Verificar sincronización inicial**
+  - ArgoCD debe detectar manifests en `k8s/backend/` y `k8s/frontend/`
+  - Ver en UI que todo esté verde
+- [ ] **Test del flujo GitOps**
+  - Cambiar algo en k8s/backend/deployment.yaml (ej: replicas: 3)
+  - Push a git
+  - Verificar que ArgoCD auto-deploya (max 3 min)

-**Referencia**: `docs/06-deployment/gitops.md`
-**URL**: https://argocd.fuq.tv (admin/LyPF4Hy0wvp52IoU)
+**Referencia completa**: `docs/06-deployment/gitops.md`
+**CLI ArgoCD**: `argocd` (instalar si no está: `brew install argocd`)
+
+**Beneficios inmediatos**:
+- ✅ Rollback con `git revert` (sin kubectl)
+- ✅ Audit trail (todo en Git)
+- ✅ UI visual del estado real vs deseado
+- ✅ Auto-healing si alguien hace kubectl directo
+
+---
+
+#### 4.2 Preview Environments con ArgoCD ApplicationSets
+**Objetivo**: Deploy automático e isolado por cada task
+**Prerequisito**: ArgoCD configurado (4.1)
+
+**Flujo deseado**:
+```
+Agent completa task
+↓
+Crea PR con código
+↓
+PR merged
+↓
+Backend crea preview manifest en git
+↓
+ArgoCD detecta nuevo manifest ← AUTOMÁTICO
+↓
+Crea namespace preview-task-{id} ← AUTOMÁTICO
+↓
+Deploy en task-{id}.r.fuq.tv ← AUTOMÁTICO
+```

-#### 4.2 Preview Environments
-**Objetivo**: Deploy automático por tarea
 **Tareas**:
- [ ] Lógica para crear namespace temporal
- [ ] Deploy app en `task-{id}.r.fuq.tv`
- [ ] Cleanup automático (TTL)
+- [ ] **Crear ApplicationSet para previews**
+  ```yaml
+  # argocd/preview-applicationset.yaml
+  apiVersion: argoproj.io/v1alpha1
+  kind: ApplicationSet
+  metadata:
+    name: preview-environments
+    namespace: argocd
+  spec:
+    generators:
+    - git:
+        repoURL: https://git.fuq.tv/admin/aiworker-gitops.git
+        directories:
+        - path: preview/*
+    template:
+      metadata:
+        name: '{{path.basename}}'
+      spec:
+        source:
+          repoURL: https://git.fuq.tv/admin/aiworker-gitops.git
+          path: '{{path}}'
+        destination:
+          server: https://kubernetes.default.svc
+          namespace: '{{path.basename}}'
+        syncPolicy:
+          automated:
+            prune: true
+            selfHeal: true
+          syncOptions:
+          - CreateNamespace=true
+  ```
+- [ ] **Crear repo separado** para manifests (opcional pero recomendado)
+  - `aiworker-gitops` → solo manifests, no código
+  - Separar code repo de config repo (GitOps best practice)
+- [ ] **Backend API para crear preview**
+  ```typescript
+  POST /api/tasks/:id/deploy-preview
+  → Genera manifests en preview/task-{id}/
+  → Commit y push a repo gitops
+  → ArgoCD detecta y deploya (automático)
+  ```
+- [ ] **Ingress dinámico por preview**
+  - `task-abc123.r.fuq.tv` → namespace `preview-task-abc123`
+  - Wildcard cert con cert-manager
+- [ ] **TTL y cleanup automático**
+  - Anotación en namespace: `ttl: 7d`
+  - CronJob que elimina namespaces expirados
+  - ArgoCD auto-prune elimina Application

 **Referencia**: `docs/06-deployment/preview-envs.md`

-#### 4.3 Staging y Production
-**Objetivo**: Pipeline completo
+---
+
+#### 4.3 Staging y Production Environments
+**Objetivo**: Pipeline completo con aprobaciones
+**Prerequisito**: ArgoCD + Preview Environments funcionando
+
+**Pipeline completo**:
+```
+Development → Preview (automático)
+             ↓
+Preview → Staging (merge a staging branch, automático)
+         ↓
+Staging → Production (aprobación manual, ArgoCD sync)
+```
+
 **Tareas**:
- [ ] Merge a staging branch
- [ ] Deploy staging automático
- [ ] Aprobación manual para production
- [ ] Rollback capability
+- [ ] **Crear Application para Staging**
+  - Repo/branch: `staging` branch
+  - Namespace: `staging`
+  - Auto-sync: true
+- [ ] **Crear Application para Production**
+  - Repo/branch: `production` branch
+  - Namespace: `production`
+  - Auto-sync: false (requiere aprobación manual)
+- [ ] **Workflow de promoción**
+  ```bash
+  # Preview aprobado
+  → Merge PR a main
+  → CI/CD build
+  → Auto-merge main → staging
+  → ArgoCD deploya staging (automático)
+
+  # Staging OK
+  → Usuario aprueba en dashboard
+  → Merge staging → production
+  → Admin hace sync manual en ArgoCD UI
+  → Deploy production
+  ```
+- [ ] **Rollback capability**
+  ```bash
+  # Opción 1: Git revert
+  git revert {bad-commit}
+  git push
+  ArgoCD auto-sync
+
+  # Opción 2: ArgoCD history
+  argocd app rollback production {revision}
+  ```
+- [ ] **Health checks y smoke tests**
+  - Pre-sync hooks en ArgoCD
+  - Post-sync validation

 **Referencia**: `docs/06-deployment/staging-production.md`

 ---

+### 📋 CHECKLIST FASE 4 (para no olvidar nada)
+
+Antes de empezar FASE 4, verificar:
+- [x] Backend deployado y funcionando
+- [x] Frontend deployado y funcionando
+- [x] Agentes Claude Code operativos
+- [x] CI/CD (Gitea Actions) funcionando
+- [ ] **ArgoCD accesible** en https://argocd.fuq.tv ← VERIFICAR PRIMERO
+
+Durante FASE 4, completar en orden:
+1. [ ] Login a ArgoCD UI (verificar credenciales)
+2. [ ] Conectar repo de Gitea
+3. [ ] Crear Applications (backend, frontend)
+4. [ ] Habilitar auto-sync
+5. [ ] Test: cambiar manifest → push → verificar auto-deploy
+6. [ ] Crear ApplicationSet para previews
+7. [ ] Test: crear preview manual → verificar auto-deploy
+8. [ ] Integrar backend API con preview creation
+9. [ ] Configurar staging/production environments
+10. [ ] Test flujo completo: task → preview → staging → prod
+
+**Documentación clave para FASE 4**:
+- `docs/06-deployment/gitops.md` - Setup completo de ArgoCD
+- `docs/06-deployment/preview-envs.md` - ApplicationSets
+- `docs/06-deployment/staging-production.md` - Multi-env workflow
+
+---
+
 ### FASE 5: Smart Specification Engine (BrainGrid-style) 🧠

 **Inspiración**: https://www.braingrid.ai/