Des runbooks qui survivent aux réorganisations

La plupart des runbooks sont écrits par la personne qui vient de régler le problème, pendant que le correctif est encore chaud. C'est le pire moment : tout ce qui lui est évident est invisible, et tout ce qu'elle a dû découvrir est déjà oublié.

Le lecteur pour qui vous écrivez est le troisième. Pas vous, pas le collègue qui était en astreinte avec vous — l'ingénieur qui arrive dans dix-huit mois, ouvre cette page à trois heures du matin, et n'a jamais vu ce système en bonne santé.

Nommez la panne, pas la procédure

Un runbook intitulé Redémarrer le service d'ingestion est classé sous une réponse. Le lecteur, lui, arrive avec un symptôme : l'alarme de profondeur de file a sonné, le tableau de bord est figé, ou un client dit que sa commande a disparu.

Titrez la page d'après ce que le lecteur voit :

• Profondeur de file au-dessus de 10 000 pendant plus de cinq minutes — et non Vider la file
• Les stocks diffèrent entre l'application magasin et l'entrepôt — et non Job de rapprochement
• La connexion réussit, puis la requête suivante renvoie 401 — et non Rotation de la clé de signature

Un symptôme peut mener à plusieurs procédures. C'est très bien : l'embranchement a sa place dans la page, là où le lecteur voit pourquoi on l'envoie d'un côté plutôt que de l'autre.

Écrivez la vérification avant l'action

Chaque étape qui modifie un état devrait être précédée de l'observation qui la justifie et suivie de celle qui la confirme. Sans la première, le lecteur devine. Sans la seconde, il ne peut pas savoir s'il a aidé.

1. Vérifier  SELECT count(*) FROM outbox WHERE published_at IS NULL;
2. Attendu   un nombre qui monte entre deux exécutions
3. Faire     redémarrer le publisher sur un seul nœud
4. Confirmer la même requête renvoie un nombre qui baisse sous 60 s
5. Sinon     arrêtez-vous et escaladez — la file n'est pas le problème

L'étape 5 est celle qu'on oublie, et c'est celle qui compte. Un runbook sans porte de sortie demande à un ingénieur fatigué de continuer à appliquer une procédure qui ne marche pas.

Consignez la décision, pas seulement la commande

La commande changera. La raison pour laquelle c'était la bonne commande, beaucoup moins.

On redémarre un seul nœud plutôt que tout le déploiement parce que le publisher prend un bail : tout redémarrer en même temps fait courir chaque nœud après le bail, et aucun ne l'obtient.

Cette phrase survit à trois refontes du script de déploiement. kubectl rollout restart non.

Gardez-le honnête en vous en servant

Un runbook que personne n'a suivi depuis sa rédaction est une hypothèse. Le moyen le moins cher de la tester : demander à quelqu'un qui ne l'a pas écrit de le suivre, à voix haute, un après-midi calme. Vingt minutes, et on trouve systématiquement deux étapes qui n'existent plus.

La mesure d'un document d'exploitation n'est pas sa complétude. C'est la capacité du suivant à agir sans avoir à vous trouver.