Versión: 1.0
Fecha: 2026-05-11
Autor: Carlos Alberto Torres Camargo (arquitecto)
Documentos relacionados: ADR-003 Política Entrega QA, POLITICA_REGRESION_QA, PIPELINE_CICD, GITFLOW_DETALLADO
Definir cuándo, quién y cómo se ejecuta un rollback en los ambientes QA y PROD del ecosistema Nebula ERP. Cubre criterios de decisión, procedimiento técnico, comunicación a stakeholders y registro post-evento.
| Término | Significado |
|---|---|
| Rollback | Reversión del ambiente a una versión previa estable y conocida, motivada por un incidente o bug crítico detectado tras un deploy. |
| Bug crítico | Defecto que justifica rollback inmediato (criterios en §3). |
| Versión estable | Tag SemVer anterior al actual cuyo deploy fue exitoso y validado. |
| Snapshot DB | Backup completo de la base de datos del ambiente afectado, tomado antes del deploy actual. |
Un defecto se clasifica como crítico (y por tanto justifica rollback) cuando se cumple al menos uno de los siguientes:
| # | Criterio | Aplicabilidad |
|---|---|---|
| 1 | Impide login o acceso al sistema para uno o más usuarios | PROD obligatorio; QA opcional |
| 2 | Pérdida o corrupción de datos (cualquier volumen) | PROD obligatorio; QA evaluación caso a caso |
| 3 | Brecha de seguridad — auth o authz roto | PROD obligatorio; QA obligatorio |
| 4 | Caída en cascada — afecta ≥ 3 microservicios simultáneamente | PROD obligatorio; QA opcional |
| 5 | Bug fiscal/contable que produce reportes incorrectos | PROD obligatorio (impacto legal); QA evaluación caso a caso |
| 6 | Performance fuera de SLA (> 5x baseline) que vuelve sistema inusable | PROD obligatorio; QA opcional |
| 7 | Indisponibilidad total del servicio (downtime no planeado > 5 min) | PROD obligatorio; QA opcional |
No son bug crítico (no justifican rollback inmediato, se atienden por flujo regular):
| Ambiente | Quién autoriza rollback | Quién ejecuta | Notificación post-acción |
|---|---|---|---|
| QA (nodo-02) | QA Lead | DevOps | Arquitecto + Backend Lead, mismo día |
| PROD (nodo-PROD) | Arquitecto | DevOps | PO + PM + stakeholders, dentro de 1h |
En ausencia del Arquitecto (vacaciones, fuera de horario), la cadena de autorización para PROD es:
Nunca un Backend Sr/Mid/Jr ejecuta rollback en PROD por iniciativa propia. DevOps solo ejecuta con autorización explícita.
Para un microservicio con imagen Docker tagged y compose:
# 1. Identificar tag estable anterior
docker images <registry>/<imagen> --format '{{.Tag}}'
# 2. Editar .env del compose del dominio afectado
vim /home/sysadmin/docker/compose/nebula/<dominio>/.env
# IMAGE_TAG=qa-<sha-anterior>-<build-anterior>
# 3. Recrear container con la versión previa
cd /home/sysadmin/docker/compose/nebula/<dominio>/
docker compose pull
docker compose up -d <servicio>
# 4. Verificar health
docker ps --filter name=<servicio>
curl -s http://<host>:<port>/<context>/actuator/health
Si el bug introdujo cambios de schema DB en QA, además:
# Identificar la migración a revertir
ssh nodo-02
docker exec postgres-qa psql -U <user> -d <db> -c "SELECT * FROM flyway_schema_history ORDER BY installed_rank DESC LIMIT 5;"
# Revertir manualmente la migración (idealmente con un script down preparado)
# Si no hay script down, restaurar desde snapshot (ver §5.3).
Análogo a QA pero con tag SemVer estable previo:
# 1. Identificar tag SemVer anterior (CHANGELOG + git tag)
git tag --sort=-creatordate | head -5
# 2. Editar .env del compose del dominio afectado en nodo-PROD
vim /home/sysadmin/docker/compose/nebula/<dominio>/.env
# IMAGE_TAG=v<X.Y.Z> (versión estable previa)
# 3. Pull y up
docker compose pull
docker compose up -d <servicio>
# 4. Verificar
docker ps --filter name=<servicio>
Si el deploy introdujo migraciones Flyway que no son reversibles vía script down:
# En el nodo afectado
docker exec postgres-<ambiente> pg_restore -U <user> -d <db> /backup/<snapshot>.dump
Pre-requisito clave: la POLITICA_REGRESION_QA §3 y el DoD-PROD obligan a tomar snapshot DB antes de cualquier deploy a PROD con migraciones. Sin snapshot disponible, el rollback DB no es posible automáticamente.
Si el bug está en código y NO requiere reversión DB:
# En el repo del servicio
git checkout main
git revert <sha-del-merge-problemático> -m 1
git push origin main
# Pipeline disparará nuevo build + deploy con la reversión.
Cuándo NO usar git revert: si hay migraciones DB, NO bastante con revert de código — la reversión del schema requiere el procedimiento §5.3.
| Stakeholder | Canal | Contenido |
|---|---|---|
| Arquitecto | Mensaje directo + email | Decisión, ambiente, justificación |
| DevOps | Mensaje directo | Autorización de ejecución |
| Backend Lead | Mensaje directo | Notificación |
| PO + PM | Decisión y plan |
Canal central (Slack/Mattermost canal #incidents o equivalente) con cronología:
HH:MM Decisión de rollback tomada.HH:MM Inicio de procedimiento.HH:MM Snapshot DB validado (si aplica).HH:MM Servicio restaurado a versión vX.Y.Z.HH:MM Health checks verdes.HH:MM Cierre del incidente, ambiente operando normalmente.Dentro de 1 hora del cierre:
Dentro de 24 horas:
architecture/incidents/INC-YYYY-MM-DD-<slug>.md con post-mortem (ver §7).Toda ejecución de rollback en PROD requiere post-mortem dentro de 48 horas, sin culpas, enfocado a mejorar el sistema.
Estructura mínima del documento INC-YYYY-MM-DD-<slug>.md:
Post-mortem se presenta en la retro del sprint siguiente y se referencia desde wiki-arquitectura/zona-interna/06-gobernanza/.
Trimestralmente se capturan y revisan:
Si solo un microservicio del lote presenta el bug crítico:
nebula-models, se requiere también pin de versión vieja de la library.Si el bug está en nebula-models, nebula-shared o nebula-commons:
vX.Y.Z+1).<nebula-X.version> al nuevo tag y se redeployean.Si el procedimiento de rollback falla (ej: snapshot DB corrupto, imagen Docker no disponible):
| Versión | Fecha | Autor | Cambio |
|---|---|---|---|
| 1.0 | 2026-05-11 | Carlos Torres | Versión inicial. Pendiente: agregar comandos específicos cuando nodo-PROD esté operativo. |