diff --git a/ROADMAP.md b/ROADMAP.md index 0ecab0b..d162613 100644 --- 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/ diff --git a/TODO-ARGOCD.md b/TODO-ARGOCD.md new file mode 100644 index 0000000..7f3ec76 --- /dev/null +++ b/TODO-ARGOCD.md @@ -0,0 +1,166 @@ +# ⚠️ RECORDATORIO: ArgoCD está INSTALADO pero NO CONFIGURADO + +**Estado**: ArgoCD instalado en el cluster, esperando configuración en FASE 4 +**Fecha instalación**: 2026-01-19 +**URL**: https://argocd.fuq.tv +**Credenciales**: admin / LyPF4Hy0wvp52IoU + +--- + +## 🚨 NO OLVIDAR + +Cuando llegues a **FASE 4** del ROADMAP, ArgoCD debe ser configurado **ANTES** de implementar preview environments. + +--- + +## 📍 Estado actual + +``` +✅ ArgoCD pods corriendo en namespace argocd +✅ ArgoCD UI accesible en https://argocd.fuq.tv +✅ Ingress configurado con TLS +✅ Credenciales funcionando +❌ NO hay Applications configuradas +❌ NO está conectado a Gitea +❌ NO está deployando nada automáticamente +``` + +**Verificar estado**: +```bash +export KUBECONFIG=~/.kube/aiworker-config +kubectl get pods -n argocd +kubectl get applications -n argocd # Debe estar vacío +``` + +--- + +## ⏭️ Próximos pasos (FASE 4) + +### 1. Quick Test (5 min) +```bash +# Verificar acceso +open https://argocd.fuq.tv +# Login: admin / LyPF4Hy0wvp52IoU + +# Verificar que UI carga correctamente +# Debe mostrar: "No applications" +``` + +### 2. Conectar Gitea (10 min) +```bash +# Install ArgoCD CLI si no está +brew install argocd + +# Login +argocd login argocd.fuq.tv --username admin --password LyPF4Hy0wvp52IoU + +# Agregar repo de Gitea +argocd repo add https://git.fuq.tv/admin/aiworker.git \ + --username admin \ + --password 159a5de2a16d15f33e388b55b1276e431dbca3f3 +``` + +### 3. Primera Application (10 min) +```bash +# Crear app para backend +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 + +# Verificar en UI +open https://argocd.fuq.tv +# Debe aparecer "backend" app en estado "Synced" +``` + +### 4. Test GitOps Flow (5 min) +```bash +# Cambiar algo en k8s/backend/deployment.yaml +# Por ejemplo: replicas: 2 → replicas: 3 + +git add k8s/backend/deployment.yaml +git commit -m "Test ArgoCD auto-sync" +git push + +# Esperar max 3 minutos +# ArgoCD debe detectar cambio y auto-deployar + +# Verificar +kubectl get deployment backend -n control-plane +# Debe mostrar 3 replicas +``` + +--- + +## 🎯 Por qué es importante NO olvidarlo + +### Sin ArgoCD (estado actual): +``` +Manual kubectl apply después de cada build +↓ +Propenso a errores +↓ +Sin audit trail +↓ +Rollback complicado +``` + +### Con ArgoCD (FASE 4): +``` +Git push → ArgoCD auto-sync +↓ +Git es source of truth +↓ +Rollback = git revert +↓ +UI visual del cluster +↓ +Preview environments automáticos ✨ +``` + +--- + +## 📊 Beneficios específicos para AiWorker + +1. **Preview Environments**: ApplicationSets crean/destruyen namespaces automáticamente +2. **Multi-tenant**: Cada task = namespace aislado via ArgoCD +3. **Audit Trail**: Todo cambio queda en Git (compliance) +4. **Rollback**: `git revert` en lugar de `kubectl rollout undo` +5. **Drift Detection**: ArgoCD detecta si alguien hace kubectl directo +6. **Self-Healing**: Si pod muere, ArgoCD lo recrea desde Git + +--- + +## 📚 Referencias + +**Documentación completa**: `docs/06-deployment/gitops.md` +**ROADMAP FASE 4**: Línea 244-404 en `ROADMAP.md` +**ArgoCD Docs**: https://argo-cd.readthedocs.io/ + +--- + +## ✅ Checklist rápida para FASE 4 + +Cuando estés listo para FASE 4, usar esta checklist: + +- [ ] Verificar ArgoCD accesible (https://argocd.fuq.tv) +- [ ] Login con credenciales (admin/LyPF4Hy0wvp52IoU) +- [ ] Instalar ArgoCD CLI (`brew install argocd`) +- [ ] Conectar repo de Gitea +- [ ] Crear Application para backend +- [ ] Crear Application para frontend +- [ ] Habilitar auto-sync +- [ ] Test: cambiar manifest → verificar auto-deploy +- [ ] Crear ApplicationSet para previews +- [ ] Integrar con backend API +- [ ] Configurar staging/production + +**Tiempo estimado FASE 4**: 2-3 horas + +--- + +**🔔 Este archivo existe para recordarte que ArgoCD está listo para usarse en FASE 4** + +**Eliminar este archivo después de completar FASE 4**