Comment rédiger un runbook de réponse aux incidents (avec modèles)

La plupart des runbooks d'incidents tombent dans deux modes de défaillance. Ils sont trop longs (un wiki de trente pages qu'aucun ingénieur d'astreinte ne lira à 3h du matin), ou ils sont trop vagues (une seule ligne qui dit « vérifiez les journaux »). Les runbooks réellement utilisés pendant les incidents suivent une structure serrée avec des commandes concrètes et des points de décision clairs. Ce guide couvre la structure qui fonctionne, avec trois modèles que vous pouvez copier pour vos types d'incidents les plus courants.

Ce qu'est un runbook et ce qu'il n'est pas

Un runbook est une checklist pour un type d'incident connu. Ce n'est pas une page wiki sur le système, pas un diagramme d'architecture, pas un modèle de postmortem. Le lecteur est un ingénieur d'astreinte qui est fatigué, possiblement à moitié endormi, et doit faire la bonne chose dans les dix prochaines minutes.

Si votre runbook explique le fonctionnement du système, il est trop long. S'il ne nomme pas des commandes spécifiques et des points de décision spécifiques, il est trop vague. La bonne taille pour un seul runbook est à peu près un écran de contenu. Si vous en avez besoin de plus, divisez-le.

La structure à cinq parties qui fonctionne

Cinq sections couvrent ce qu'un ingénieur d'astreinte a besoin. Utilisez cette structure pour chaque runbook de votre collection.

• Symptôme : à quoi ressemble l'alerte. Citez le texte exact de l'alerte. L'ingénieur doit le reconnaître en quelques secondes.
• Impact : qui est affecté et comment. Face aux clients ? Interne ? Simple bruit de surveillance ? Définit l'urgence.
• Diagnostics : les trois commandes ou liens qui confirment le diagnostic. Pas vérifier les journaux, mais `kubectl logs -n prod web-deployment -c app`.
• Résolution : les commandes ou actions spécifiques pour corriger. Numérotées, idempotentes, sûres à réessayer.
• Escalade : qui réveiller si la résolution ne fonctionne pas. Nom et numéro de téléphone.

Modèle : runbook de saturation des connexions à la base de données

Type d'incident de production le plus courant. Le pool de connexions à la base de données est plein, les nouvelles requêtes expirent, la surveillance déclenche des alertes de latence élevée.

Symptôme : temps de réponse p95 supérieur à 5 secondes sur /api/health. Impact : les points de terminaison API orientés clients expirent. Diagnostics : kubectl exec dans le pod d'app et exécutez pg_stat_activity. Recherchez les requêtes longues. Résolution : annulez les requêtes longues avec pg_cancel_backend, augmentez la taille du pool de 20 % avec helm upgrade, redémarrez les pods affectés. Escalade : alertez le responsable de la base de données si le pool est toujours saturé après 10 minutes.

Modèle : runbook d'expiration de certificat SSL

Prévisible, évitable, et cela arrive quand même à presque toutes les équipes. Le runbook est court car la réponse est courte.

• Symptôme : l'alerte SSL se déclenche avec « expire dans 7 jours » ou « expiré ».
• Impact : chaque navigateur affiche la page d'avertissement rouge une fois le certificat expiré. La conversion tombe à zéro.
• Diagnostics : exécutez `echo
• openssl s_client -servername DOMAIN -connect DOMAIN:443 2>/dev/null
• openssl x509 -noout -dates` pour voir la date notAfter du certificat actuel.
• Résolution : exécutez le script de renouvellement manuellement (`certbot renew --force-renewal` ou équivalent), puis rechargez nginx/l'équilibreur de charge. Vérifiez avec la même commande openssl.
• Escalade : alertez DevOps si certbot échoue. Le certificat doit être renouvelé manuellement avant l'expiration.

Modèle : runbook de panne d'un fournisseur tiers

Quand une dépendance tierce (Stripe, Postmark, S3, un fournisseur d'authentification) est la véritable panne, votre travail est de la reconnaître, de la communiquer, et de ne pas gaspiller du temps à déboguer votre propre code.

Symptôme : la fonctionnalité concernée ne fonctionne pas, vos propres moniteurs sont sinon au vert. Diagnostics : ouvrez la page de statut du fournisseur dans un nouvel onglet. Recherchez les commits récents pour les modifications de l'intégration. Résolution : publiez une mise à jour sur votre page de statut reconnaissant l'incident amont, avec un lien vers la page de statut du fournisseur. Désactivez la fonctionnalité derrière un feature flag si la dégradation est grave. Escalade : uniquement si la dégradation dure plus d'une heure sans reconnaissance du fournisseur amont.

Où les conserver et comment les maintenir à jour

Conservez les runbooks dans le même dépôt git que le code de l'application. Reliez-les à partir du message d'alerte lui-même. Examinez-les après chaque incident : si le runbook était incorrect, mettez-le à jour maintenant pendant que l'incident est frais. Un runbook qui n'a pas été mis à jour depuis un an n'est probablement plus exact. Planifiez un examen trimestriel de la collection de runbooks. Supprimez ceux qui ne s'appliquent plus. Ajoutez les nouveaux. Traitez-les comme du code.