Cómo redactar un runbook de respuesta a incidentes (con plantillas)

La mayoría de los runbooks de incidentes caen en dos modos de fallo. Son demasiado largos (una wiki de treinta páginas que ningún ingeniero de guardia leerá a las 3 de la madrugada) o son demasiado vagos (una sola línea que dice «revisa los logs»). Los runbooks que realmente se usan durante los incidentes siguen una estructura ajustada con comandos concretos y puntos de decisión claros. Esta guía cubre la estructura que funciona, con tres plantillas que puedes copiar para tus tipos de incidente más comunes.

Qué es un runbook y qué no es

Un runbook es una lista de comprobación para un tipo de incidente conocido. No es una página de wiki sobre el sistema, ni un diagrama de arquitectura, ni una plantilla de postmortem. El lector es un ingeniero de guardia que está cansado, posiblemente medio dormido, y necesita hacer lo correcto en los próximos diez minutos.

Si tu runbook explica cómo funciona el sistema, es demasiado largo. Si no nombra comandos específicos ni puntos de decisión concretos, es demasiado vago. El tamaño adecuado para un único runbook es aproximadamente una pantalla de contenido. Si necesitas más, divídelo.

La estructura de cinco partes que funciona

Cinco secciones cubren lo que necesita un ingeniero de guardia. Usa esta estructura para cada runbook de tu colección.

• Síntoma: cómo se ve la alerta. Cita el texto real de la alerta. El ingeniero debe reconocerla en segundos.
• Impacto: a quién afecta y cómo. ¿De cara al cliente? ¿Interno? ¿Solo ruido de monitorización? Determina la urgencia.
• Diagnóstico: los tres comandos o enlaces que confirman el diagnóstico. No «revisa los logs», sino «kubectl logs -n prod web-deployment -c app».
• Resolución: los comandos o acciones específicas para solucionarlo. Numerados, idempotentes, seguros para reintentar.
• Escalado: a quién despertar si la resolución no funciona. Nombre y número de teléfono.

Plantilla: un runbook de saturación de conexiones a base de datos

El tipo de incidente de producción más común. El pool de conexiones a la base de datos está lleno, las nuevas solicitudes expiran y la monitorización dispara alertas de latencia elevada.

Síntoma: «tiempo de respuesta p95 superior a 5 segundos en /api/health». Impacto: los endpoints de API de cara al cliente expiran. Diagnóstico: ejecuta kubectl exec en el pod de la aplicación y lanza pg_stat_activity. Busca consultas de larga duración. Resolución: cancela las consultas más largas con pg_cancel_backend, escala el tamaño del pool en un 20 % con helm upgrade, reinicia los pods afectados. Escalado: avisa al responsable de la base de datos si el pool sigue saturado tras 10 minutos.

Plantilla: un runbook de expiración de certificado SSL

Predecible, prevenible y, aun así, le pasa a casi todos los equipos tarde o temprano. El runbook es corto porque la respuesta es corta.

• Síntoma: el monitor SSL se dispara con «expira en 7 días» o «expirado».
• Impacto: todos los navegadores muestran la página roja de advertencia en cuanto caduca el certificado. La conversión cae a cero.
• Diagnóstico: ejecuta `echo
• openssl s_client -servername DOMAIN -connect DOMAIN:443 2>/dev/null
• openssl x509 -noout -dates` para ver la fecha notAfter del certificado actual.
• Resolución: ejecuta el script de renovación manualmente (`certbot renew --force-renewal` o equivalente) y luego recarga nginx o el balanceador de carga. Verifica con el mismo comando openssl.
• Escalado: avisa a DevOps si certbot falla. El certificado debe renovarse manualmente antes de la expiración.

Plantilla: un runbook de caída de proveedor externo

Cuando una dependencia de terceros (Stripe, Postmark, S3, un proveedor de autenticación) es la causa real de la caída, tu trabajo es reconocerlo, comunicarlo y no perder tiempo depurando tu propio código.

Síntoma: la funcionalidad correspondiente está fallando, pero tus propios monitores están verdes. Diagnóstico: abre la página de estado del proveedor en una nueva pestaña. Busca cambios recientes en commits relacionados con la integración. Resolución: publica una actualización en tu propia página de estado reconociendo el incidente externo, con un enlace a la página de estado del proveedor. Desactiva la funcionalidad detrás de un feature flag si la degradación es severa. Escalado: solo si la degradación dura más de una hora sin que el proveedor externo dé acuse de recibo.

Dónde guardarlos y cómo mantenerlos actualizados

Guarda los runbooks en el mismo repositorio git que el código de la aplicación. Enlázalos desde el propio mensaje de alerta. Revísalos después de cada incidente: si el runbook estaba equivocado, actualízalo ahora que el incidente está fresco. Un runbook que no se ha actualizado en un año probablemente ya no es preciso. Programa una revisión trimestral de la colección de runbooks. Elimina los que ya no aplican. Añade los nuevos. Trátalos como código.