Plantilla de Checklist de Despliegue

Visión General

Una checklist de despliegue es una lista de verificación previa al release que cada despliegue debe superar antes, durante y después de llegar a producción. Los despliegues en producción son momentos de alto riesgo: un solo paso omitido puede causar caídas, pérdida de datos o exposiciones de seguridad. Esta plantilla da a cada release el mismo camino de verificación, desde los tests pre-merge hasta el monitoreo post-despliegue, para que la calidad deje de depender de quién despliegue ese día.

Cuándo Usar

Usa este recurso cuando:

• Preparas cualquier despliegue a producción o staging
• Integras nuevos miembros del equipo al proceso de release
• Auditas el proceso de despliegue después de un incidente
• Defines criterios de go/no-go para un servicio o pipeline nuevo

No la uses para despliegues en desarrollo local ni para rollouts que solo activan una flag sin cambios de infraestructura o esquema; ahí basta una verificación de dos líneas.

Para la parte de comunicación del release, combina esta checklist con la Plantilla de Comunicación de Rollout.

Solución

# Checklist de Despliegue: `<Nombre del Release>`

## Metadatos del Release

| Campo | Valor |
|-------|-------|
| Servicio | `nombre` |
| Versión | `x.y.z` |
| Rama / Commit | `main@abc1234` |
| Desplegador | `@username` |
| Fecha | `YYYY-MM-DD HH:MM UTC` |
| Ticket / PR | `PROJ-123` |

## 1. Pre-Despliegue

### 1.1. Código y Tests

- [ ] Todos los checks de CI pasan (lint, tests unitarios, tests de integración)
- [ ] Code review aprobado por al menos un ingeniero senior
- [ ] Sin alertas de seguridad sin resolver (Snyk, Dependabot)
- [ ] Migraciones de base de datos revisadas para compatibilidad hacia atrás
- [ ] Feature flags configuradas y por defecto apagadas

### 1.2. Infraestructura

- [ ] Entorno staging desplegado y validado
- [ ] Capacidad de producción verificada (CPU, memoria, disco)
- [ ] Reglas de autoscaling revisadas (réplicas mínimas / máximas)
- [ ] Artefacto de rollback construido y almacenado (imagen Docker, AMI)
- [ ] Plan de invalidación de caché CDN documentado (si aplica)

### 1.3. Comunicación

- [ ] Stakeholders notificados de la ventana de despliegue
- [ ] Ingeniero on-call disponible
- [ ] Página de estado actualizada a "Mantenimiento" (si hay downtime esperado)
- [ ] Equipos de atención al cliente informados de los cambios

## 2. Despliegue

### 2.1. Base de Datos (si aplica)

- [ ] Scripts de migración probados contra una copia de datos de producción
- [ ] Migración ejecutada con `ALTER TABLE ... ADD COLUMN` (no operaciones destructivas primero)
- [ ] Duración de la migración estimada y aprobada por el DBA
- [ ] Script de rollback preparado para cambios destructivos

### 2.2. Aplicación

- [ ] Desplegar usando estrategia blue/green o canary
- [ ] Monitorear tasa de error durante 5 minutos después de cada incremento de canary
- [ ] Verificar que health checks devuelven 200 OK
- [ ] Confirmar que nuevos pods/contenedores reciben tráfico

### 2.3. Verificación

- [ ] Smoke tests pasan contra endpoints de producción
- [ ] Flujos críticos de usuario probados (login, checkout, búsqueda)
- [ ] Logs no muestran errores o excepciones inesperadas
- [ ] Métricas dentro de la línea base (latencia p95, tasa de error, CPU)

## 3. Post-Despliegue

### 3.1. Validación

- [ ] Feature flags habilitadas incrementalmente (5% → 25% → 100%)
- [ ] Resultados de tests A/B monitoreados (si aplica)
- [ ] Soporte al cliente informado de nuevas capacidades o cambios
- [ ] Documentación actualizada (docs de API, runbooks, wiki)

### 3.2. Monitoreo

- [ ] Dashboards revisados por anomalías (tráfico, errores, latencia)
- [ ] Alertas disparándose como se espera (sin falsos positivos ni alertas silenciadas)
- [ ] Monitoreo sintético pasando (Pingdom, Datadog Synthetics)
- [ ] Seguimiento de errores revisado (Sentry, Rollbar) para nuevos issues

### 3.3. Limpieza

- [ ] Versiones antiguas escaladas hacia abajo después de confirmar estabilidad (30 min)
- [ ] Ramas de funcionalidad eliminadas
- [ ] Log de despliegue archivado para auditoría
- [ ] Página de estado actualizada a "Operacional"

Explicación

La checklist está ordenada por riesgo: calidad de código primero, luego preparación de infraestructura, luego ejecución, luego validación. El artefacto de rollback es un requisito estricto porque no puedes desplegar de forma segura lo que no puedes revertir rápidamente; para estrategias que mantienen el rollback por debajo del minuto, consulta la checklist de despliegue zero-downtime. Los incrementos de canary con health checks detectan problemas antes de que afecten a todos los usuarios, y el monitoreo post-despliegue se extiende más allá del momento del despliegue porque algunos problemas (fugas de memoria, calentamiento de caché) solo aparecen después de tráfico sostenido.

La sección de base de datos merece su propia disciplina. Ejecuta los cambios de esquema con el patrón expand-and-contract: agrega primero las columnas o tablas nuevas, despliega la versión de la aplicación que tolera ambos esquemas, y solo elimina las estructuras viejas en un release posterior, cuando ya nada las lea. Así cada despliegue individual sigue siendo reversible; una migración destructiva enviada junto con el código que depende de ella es la forma clásica en que los equipos pierden su vía de rollback.

Criterios de Go/No-Go

Un ítem de checklist sin umbral es un debate esperando a ocurrir. Asigna una señal medible a cada etapa para que la decisión la tomen los números y no la presión del momento:

Etapa	Señal de Go	Señal de No-Go
CI	Lint, tests unitarios y de integración en verde; cero alertas críticas sin resolver	Cualquier check rojo o flaky, migración sin revisar
Staging	Smoke tests pasan; métricas iguales a la línea base	Latencia p95 o tasa de error por encima de la base +10%
Canary	Tasa de error < 0.1% y p95 dentro de la base durante 5-10 min	Tasa de error > 0.5% o health checks fallando repetidamente
Post-despliegue	Sin alertas nuevas en 30 min; checks sintéticos en verde	Errores nuevos en tracking por encima de la base horaria

Trata cualquier No-Go como un disparador de rollback, no como un punto de discusión. La checklist existe para eliminar la negociación cuando el sistema ya te está diciendo que algo va mal.

Dimensiona las ventanas de observación según el radio de impacto, no según el reloj. Una API sin estado detrás de una feature flag suele poder salir con un canary de 10 minutos y una vigilancia post-despliegue de 30, mientras que un release que toca pagos, autenticación o esquemas se gana una estabilización más larga: una hora o más en cada incremento de canary y alguien asignado explícitamente a mirar dashboards, en lugar de asumir que las alertas avisarán. Escribe la ventana en la checklist antes de empezar el despliegue; decidir “un poco más” a mitad del release es la forma en que una vigilancia de 15 minutos se convierte en cero sin que nadie lo note.

Script de Despliegue Canary

El script siguiente automatiza las secciones 2.2 y 2.3 para un entorno Kubernetes usando un VirtualService de Istio para mover el tráfico. Requiere BUILD_TAG (el tag de imagen a liberar) y revierte automáticamente si la tasa de error del canary supera el 1% o el endpoint de métricas no responde.

#!/bin/bash
# Despliegue canary con health checks (Kubernetes + Istio VirtualService)
set -euo pipefail

SERVICE="api"
NAMESPACE="production"
CANARY_PERCENT=10
BUILD_TAG="${BUILD_TAG:?required — set to the image tag you are releasing}"

echo "=== Despliegue Canary: $SERVICE ==="

# Paso 1: Desplegar canary
echo "[1/5] Desplegando pod canary..."
kubectl set image "deployment/$SERVICE-canary" "$SERVICE=registry.example.com/$SERVICE:$BUILD_TAG" -n "$NAMESPACE"
kubectl rollout status "deployment/$SERVICE-canary" -n "$NAMESPACE" --timeout=120s

# Paso 2: Enrutar 10% de tráfico al canary
echo "[2/5] Enrutando $CANARY_PERCENT% de tráfico al canary..."
kubectl patch virtualservice "$SERVICE" -n "$NAMESPACE" --type merge -p '{"spec":{"http":[{"route":[{"destination":{"host":"'"$SERVICE"'","subset":"stable"},"weight":90},{"destination":{"host":"'"$SERVICE"'","subset":"canary"},"weight":'"$CANARY_PERCENT"'}]}]}}'

# Paso 3: Monitorear durante 10 minutos
echo "[3/5] Monitoreando canary durante 10 minutos..."
sleep 600

# Un resultado vacío se trata como fallo: salud desconocida no es saludable
ERROR_RATE=$(kubectl exec -n "$NAMESPACE" "deployment/$SERVICE-canary" -- curl -s http://localhost:8080/metrics | grep error_rate | awk '{print $2}' || true)
ERROR_RATE="${ERROR_RATE:-1}"
echo "  Tasa de error: $ERROR_RATE"

if (( $(echo "$ERROR_RATE > 0.01" | bc -l) )); then
  echo "  ERROR: Tasa de error muy alta, revirtiendo canary"
  kubectl patch virtualservice "$SERVICE" -n "$NAMESPACE" --type merge -p '{"spec":{"http":[{"route":[{"destination":{"host":"'"$SERVICE"'","subset":"stable"},"weight":100}]}]}}'
  kubectl delete "deployment/$SERVICE-canary" -n "$NAMESPACE"
  exit 1
fi

# Paso 4: Promover a rollout completo
echo "[4/5] Promoviendo canary a rollout completo..."
kubectl set image "deployment/$SERVICE" "$SERVICE=registry.example.com/$SERVICE:$BUILD_TAG" -n "$NAMESPACE"
kubectl rollout status "deployment/$SERVICE" -n "$NAMESPACE" --timeout=300s

# Paso 5: Limpiar recursos canary
echo "[5/5] Limpiando recursos canary..."
kubectl patch virtualservice "$SERVICE" -n "$NAMESPACE" --type merge -p '{"spec":{"http":[{"route":[{"destination":{"host":"'"$SERVICE"'","subset":"stable"},"weight":100}]}]}}'
kubectl delete "deployment/$SERVICE-canary" -n "$NAMESPACE"

echo "=== Despliegue Canary Completado ==="

Si no usas Istio, cambia los parches de virtualservice por las anotaciones canary de tu ingress controller o por tu service mesh; la forma desplegar → enrutar → medir → promover se mantiene igual.

Plantilla de Comunicación de Despliegue

=== Comunicación de Despliegue ===

Canal: #deployments
Responsable: alice@example.com
Fecha: 2026-07-11 14:00 UTC

Iniciando despliegue: API v2.3.1
  Nivel de riesgo: MEDIO
  Cambios: Bug fixes + mejoras de rendimiento
  Rollback: git revert + redeploy (est. 5 min)

14:00 - Desplegando a staging... DONE
14:05 - Smoke tests en staging... PASS
14:10 - Desplegando canary (10% tráfico)...
14:20 - Métricas canary OK (tasa de error: 0.02%)
14:25 - Promoviendo a rollout completo...
14:30 - Rollout completo. Monitoreando 30 min.
15:00 - Despliegue confirmado estable. Estado: OPERACIONAL.

Si se detectan problemas: contactar #on-call, ref CHG-2026-07-11-001
Comando de rollback: ./scripts/rollback.sh API v2.3.0

Variantes

Contexto	Enfoque	Notas
Hotfix	Checklist abreviada	Omitir pasos no críticos, enfocarse en tests y rollback
Mantenimiento programado	Sección de comunicación extendida	Incluir ventana de mantenimiento, notificaciones a clientes
Cambio solo de base de datos	Sección de base de datos enfatizada	Requerir aprobación del DBA, período de estabilización más largo
Primer despliegue de un servicio nuevo	Checklist completa más revisión de infraestructura	Añadir checks de DNS, TLS y runbook antes del go-live

Ejemplo Rellenado

Así queda la checklist rellenada para un release real: api-billing v2.4.0, que publica una migración de esquema detrás de una feature flag:

# Checklist de Despliegue: api-billing v2.4.0

| Campo | Valor |
|-------|-------|
| Servicio | api-billing |
| Versión | 2.4.0 |
| Rama / Commit | main@f31c9d2 |
| Desplegador | @mpaulenko |
| Fecha | 2026-10-16 14:00 UTC |
| Ticket / PR | BILL-882 |

## Pre-Despliegue

- [x] CI en verde en el PR #412, aprobado por dos ingenieros senior
- [x] Migración `20261015_add_refund_reason.sql` probada en copia de producción (12 min)
- [x] Imagen de rollback `api-billing:2.3.9` etiquetada en el registry
- [x] Feature flag `refund_v2` configurada, apagada por defecto
- [x] Canal #deployments notificado, ingeniero on-call confirmado

## Despliegue

- [x] Migración ejecutada en 11 min — solo expand, sin drops
- [x] Canary al 10% durante 10 min: tasa de error 0.02%, p95 180ms (base 172ms)
- [x] Rollout completo a las 14:35 UTC

## Post-Despliegue

- [x] `refund_v2` habilitada 5% → 25% → 100% en 2 horas
- [x] Sin issues nuevos en Sentry durante la ventana de observación de 30 min
- [x] Pods antiguos escalados a 0 a las 15:10 UTC
- [ ] Revisión de la checklist programada tras la próxima revisión de incidente

Hay dos detalles del ejemplo rellenado que importan más que los checkmarks. La migración queda registrada con su duración medida: la próxima vez que alguien estime un cambio parecido tendrá un número real y no una suposición. Y la ventana de observación tiene un responsable explícito: alguien anotó que los pods bajaron a cero a las 15:10, lo que significa que el paso de limpieza realmente se ejecutó en lugar de darse por hecho. Los despliegues se degradan más rápido por confirmaciones vagas que por pasos faltantes.

La plantilla en blanco, este ejemplo rellenado y el script canary están publicados como archivos en el repositorio complementario: cópialos directamente en tu wiki o repo.

Adaptar la Checklist a tu Pipeline

La checklist funciona como documento, pero todo ítem que se pueda automatizar debería convertirse en un gate del pipeline en lugar de un checkbox manual:

Sección de la checklist	Gate del pipeline
Código y Tests	Status checks obligatorios más un job de escaneo de seguridad
Infraestructura	Job de despliegue a staging seguido de un smoke test de capacidad
Base de datos	Paso de aprobación manual con el diff de la migración adjunto
Canary	Controlador de entrega progresiva (Argo Rollouts, Flagger)
Monitoreo post-despliegue	Análisis automático de métricas o espera temporizada antes de promover

Argo Rollouts y Flagger codifican exactamente el bucle canary → análisis → promoción de la sección 2.2, y ambos pueden abortar un rollout automáticamente cuando las métricas empeoran. Mantén pasos de aprobación manual donde haga falta criterio —aviso a stakeholders, visto bueno de negocio, un segundo par de ojos— y automatiza todo lo mecánico. Para un ejemplo completo del pipeline que lo rodea, consulta la guía de CI/CD con GitHub Actions.

Guarda la propia checklist junto al pipeline como código —un YAML o un markdown en el repo— para que cada cambio pase por la misma revisión que la aplicación. La automatización también tiene un suelo: un equipo que despliega una vez al mes saca más de una checklist afilada de una página que de un controlador de entrega progresiva que tiene que mantener. Adopta la herramienta cuando la frecuencia de despliegue y el coste del fallo justifiquen operarla, no antes.

Lo que Funciona

1. Automatizar cada checkbox que se pueda automatizar (tests, smoke tests, health checks)
2. Ejecutar la checklist en un documento o herramienta compartida para que una segunda persona confirme los pasos
3. Nunca desplegar un viernes por la tarde o antes de festivos salvo que sea un fix crítico
4. Mantener la checklist lo bastante corta para completarse en 15 minutos en despliegues rutinarios
5. Revisar y actualizar la checklist después de cada incidente que involucre un despliegue

Errores Comunes

1. Omitir la validación en staging porque “el cambio es pequeño”
2. Desplegar sin un plan de rollback probado, o con un plan que nadie ha ejecutado nunca
3. Publicar una migración destructiva en el mismo release que el código que depende de ella
4. No monitorear después de que el despliegue está “completo”; las fugas de memoria aparecen bajo carga sostenida
5. Desplegar varios cambios no relacionados en el mismo release, convirtiendo el rollback en todo-o-nada
6. Permitir que los desplegadores trabajen solos sin un segundo par de ojos

Troubleshooting

• El pipeline falla en silencio: activa el logging verbose y guarda los artefactos del pipeline entre etapas para inspeccionar el estado exacto que falló.
• El contenedor falla al arrancar: comprueba que las variables de entorno, los secretos y los archivos de configuración están montados correctamente. Lee las primeras 50 líneas de logs antes de escalar réplicas.
• El despliegue se revierte una y otra vez: verifica health checks, límites de recursos y startup probes. Un readiness probe que falla es causa frecuente de reinicios en bucle.
• Builds de CI lentos: cachea dependencias y capas de Docker. Divide las suites de tests grandes en jobs paralelos para reducir el tiempo total.
• Deriva entre entornos: usa infraestructura como código y artefactos inmutables para que staging realmente anticipe producción.

Lecturas Recomendadas

• Docs de Kubernetes — kubectl rollout: los comandos de rollout sobre los que se apoya el script canary.
• Docs de Istio — Traffic Shifting: enrutado ponderado usado para los incrementos de canary.
• Documentación de Argo Rollouts: automatización del bucle canary → análisis → promoción.
• Martin Fowler — Evolutionary Database Design: el enfoque expand-and-contract detrás de la sección de migraciones.