Runbooks que sobreviven a una reorganización

La mayoría de los runbooks los escribe quien acaba de resolver el problema, mientras la solución sigue caliente. Es el peor momento posible: todo lo que le resulta obvio es invisible, y todo lo que tuvo que descubrir ya se le ha olvidado.

El lector para el que escribe es el tercero. No usted, ni el compañero que estaba de guardia — el ingeniero que entra dentro de dieciocho meses, abre esta página a las tres de la madrugada y nunca ha visto el sistema sano.

Nombre el fallo, no el procedimiento

Un runbook titulado Reiniciar el servicio de ingesta está archivado bajo una respuesta. El lector llega con un síntoma: saltó la alarma de profundidad de cola, el panel está congelado, o un cliente dice que su pedido desapareció.

Titule la página por lo que el lector ve:

• Profundidad de cola por encima de 10 000 durante más de cinco minutos — y no Vaciar la cola
• El stock difiere entre la aplicación de tienda y el almacén — y no Trabajo de conciliación
• El login funciona y la siguiente petición devuelve 401 — y no Rotar la clave de firma

Un síntoma puede llevar a varios procedimientos. No pasa nada: la bifurcación va dentro de la página, donde el lector ve por qué se le manda a un lado y no al otro.

Escriba la comprobación antes que la acción

Cada paso que cambia un estado debería ir precedido de la observación que lo justifica y seguido de la que lo confirma. Sin la primera, el lector adivina. Sin la segunda, no puede saber si ha ayudado.

1. Comprobar SELECT count(*) FROM outbox WHERE published_at IS NULL;
2. Esperado  un número que sube entre dos ejecuciones
3. Hacer     reiniciar el publisher en un solo nodo
4. Confirmar la misma consulta devuelve un número que baja en 60 s
5. Si no     deténgase y escale — la cola no es el problema

El paso 5 es el que se omite, y es el que importa. Un runbook sin salida le pide a un ingeniero cansado que siga aplicando un procedimiento que no funciona.

Registre la decisión, no solo el comando

El comando cambiará. La razón por la que era el comando correcto, mucho menos.

Reiniciamos un nodo y no todo el despliegue porque el publisher toma un lease: reiniciarlos todos a la vez hace que compitan por él y ninguno lo consigue.

Esa frase sobrevive a tres reescrituras del script de despliegue. kubectl rollout restart no.

Manténgalo honesto usándolo

Un runbook que nadie ha seguido desde que se escribió es una hipótesis. La forma más barata de probarla: que alguien que no lo escribió lo siga, en voz alta, una tarde tranquila. Veinte minutos, y aparecen siempre dos pasos que ya no existen.

La medida de un documento de operaciones no es su completitud. Es si el siguiente puede actuar sin tener que encontrarle a usted.