Runbooks : vos procédures d'urgence documentées

Mise à jour : 29/12/2025

Il est 3 heures du matin. Votre téléphone sonne : alerte critique sur le serveur de production. Le service principal ne répond plus. Vous savez qu’il existe une procédure pour ce cas… mais où est-elle déjà ? Dans le wiki ? Dans un email ? Dans la tête de votre collègue qui est en vacances ?

Vous improvisez, vous tapez des commandes de mémoire. Une erreur. Une heure plus tard, le service est rétabli, mais à quel prix ?

Un runbook aurait transformé cette nuit cauchemardesque en intervention de 15 minutes.

Qu’est-ce qu’un runbook ?

L’analogie de la recette de cuisine

Imaginez que vous devez préparer un bœuf bourguignon pour la première fois :

Sans recette : vous improvisez, vous ajoutez du vin « à peu près », vous laissez mijoter « un certain temps ». Même si le plat est réussi, vous ne saurez pas reproduire le résultat.
Avec une bonne recette : vous suivez les étapes, vous obtenez un résultat prévisible, et n’importe qui peut reproduire le même plat.

Un runbook, c’est la recette de vos interventions techniques. C’est un document qui décrit pas à pas comment réagir à une situation donnée. Comme une recette, il doit être assez détaillé pour qu’une personne qui n’a jamais fait l’opération puisse la réaliser.

Définition simple

Le terme runbook (de « run » = exécuter) désigne un document opérationnel qui formalise les procédures d’exploitation. Contrairement à une documentation qui explique le « pourquoi », un runbook se concentre sur le « comment agir ».

Un bon runbook répond à quatre questions :

Quoi faire ? — Les étapes jusqu’à la résolution
Comment ? — Les commandes exactes, pas juste « redémarrez le service »
Qui contacter ? — Si la procédure ne fonctionne pas
Comment vérifier ? — Que le problème est réellement résolu

Pourquoi « runbook » et pas « documentation » ?

La différence est fondamentale :

La documentation explique comment un système fonctionne.
Un runbook prescrit ce qu’il faut faire dans une situation précise.

Vous lisez une documentation pour apprendre. Vous lisez un runbook pour agir.

Documentation	Runbook
« Le service nginx écoute sur le port 443 »	« Si nginx ne répond pas : 1) Vérifiez avec `systemctl status nginx`… »
Objectif : comprendre	Objectif : résoudre
Lecture au calme	Lecture sous pression
Peut faire des dizaines de pages	Idéalement une page

Les deux sont complémentaires : la documentation pour comprendre, les runbooks pour agir en urgence.

Les trois types de runbooks

Runbooks d’incidents : comment réagir quand quelque chose casse.

Ce sont les runbooks les plus critiques, utilisés quand le système est en feu et que le temps presse.

Exemples : disque plein, service qui ne répond plus, erreurs 500 en cascade, base de données inaccessible, certificat SSL expiré, fuite mémoire.

Ces runbooks sont utilisés en urgence, souvent la nuit. Ils doivent être ultra-clairs, testés régulièrement, et immédiatement accessibles (lien direct depuis l’alerte).

Pourquoi les runbooks sont essentiels

Le problème de la connaissance tacite

Dans chaque équipe, il y a cette personne qu’on appelle à 3h du matin parce qu’elle seule connaît « le truc » pour redémarrer le service récalcitrant.

Cette connaissance qui existe uniquement dans la tête de certaines personnes crée un point de défaillance unique (SPOF) humain. Que se passe-t-il quand cette personne part en vacances, change d’équipe, quitte l’entreprise, ou est simplement malade le jour de l’incident critique ?

Sans runbooks, la connaissance reste dans les têtes. Avec des runbooks, elle est accessible à tous.

L’effet du stress sur la prise de décision

Pourquoi faites-vous des erreurs stupides à 3h du matin ? Parce que le stress aigu modifie votre façon de réfléchir :

Régression vers les automatismes — Sous stress, le cerveau bascule vers les réactions rapides plutôt que la réflexion analytique.
Raccourcis mentaux dangereux — « La dernière fois c’était la BDD » — et vous passez 30 minutes sur la mauvaise piste.
Oubli des étapes basiques — On débugge pendant une heure un service qui… n’était pas démarré.

Un runbook compense ces limitations : il fournit une liste d’actions à suivre mécaniquement. C’est le même principe que les checklists de pilotes d’avion — même les experts les utilisent pour éliminer le risque d’oubli.

Les bénéfices mesurables

Aspect	Sans runbook	Avec runbook
Temps de résolution	Variable selon qui intervient	Prévisible et optimisé
Risque d’erreur	Élevé (improvisation)	Réduit (procédure testée)
Temps de formation	Long (compagnonnage)	Court (lecture + simulation)
Stress de l’astreinte	Élevé	Gérable

Les organisations avec des runbooks bien maintenus rapportent typiquement une réduction de 40-60% du temps de résolution.

Comparaison des approches

Anatomie d’un bon runbook

La structure minimale

Chaque runbook devrait contenir au minimum ces éléments :

# Titre : [Nom de l'incident ou de l'opération]

## Symptômes
Comment reconnaître cette situation ?

## Prérequis
- Accès nécessaires
- Outils requis
- Connaissances préalables

## Procédure
Étapes numérotées à suivre

## Vérification
Comment confirmer que le problème est résolu ?

## Escalade
Qui contacter si ça ne fonctionne pas ?

## Historique
- Date : modification
- Date : création

Chaque section a son rôle : le titre doit correspondre au nom de l’alerte, les symptômes permettent de confirmer le diagnostic, les prérequis évitent de se retrouver bloqué en pleine procédure, et l’escalade indique quoi faire si ça ne marche pas.

Exemple concret : disque plein

Voici un runbook complet pour un incident courant : la saturation du disque /var/log.

# Runbook : Disque /var/log plein (alerte DISK_VAR_LOG_CRITICAL)

## Symptômes
- Alerte "DISK_VAR_LOG_CRITICAL" dans le monitoring
- Le serveur répond lentement ou plus du tout
- Erreurs "No space left on device" dans les logs applicatifs

## Prérequis
- Accès SSH au serveur concerné
- Droits sudo
- Connaissance de base des commandes Linux

## Procédure

### 1. Se connecter au serveur
ssh admin@<serveur-concerné>

### 2. Vérifier l'état du disque
df -h /var/log

### 3. Identifier les fichiers les plus volumineux
sudo du -ah /var/log | sort -rh | head -20

### 4. Vérifier si logrotate fonctionne
sudo logrotate -d /etc/logrotate.conf 2>&1 | head -50

### 5. Supprimer les logs anciens (si logrotate OK)
sudo find /var/log -name "*.log" -mtime +7 -delete
sudo find /var/log -name "*.gz" -mtime +30 -delete

### 6. Forcer la rotation si nécessaire
sudo logrotate -f /etc/logrotate.conf

### 7. Redémarrer rsyslog si les logs ne s'écrivent plus
sudo systemctl restart rsyslog

## Vérification
df -h /var/log
# Le pourcentage d'utilisation doit être < 80%

## Escalade
Si l'espace ne se libère pas après ces étapes :
1. Vérifier qu'aucun processus ne garde un fichier supprimé ouvert :
   sudo lsof +L1 /var/log
2. Contacter l'équipe infrastructure : infra@example.com
3. Si critique : appeler l'astreinte N+1 (voir tableau d'escalade)

## Cause racine à investiguer
Après résolution, créer un ticket pour investiguer :
- Pourquoi logrotate n'a pas fonctionné ?
- Y a-t-il une application qui génère trop de logs ?
- Faut-il augmenter l'espace disque ?

## Historique
- 2025-01-15 : Ajout vérification lsof (incident #1234)
- 2024-09-01 : Création initiale

Les 7 qualités d’un runbook efficace

Actionnable — Chaque étape décrit une action concrète, pas une explication. Mauvais : « Le service peut être redémarré ». Bon : « Exécutez sudo systemctl restart nginx ».
Testable — La procédure a été exécutée en conditions réelles ou simulées.
Autonome — Contient toutes les informations nécessaires, pas de « voir documentation X ».
Concis — Va droit au but. Les explications détaillées vont dans une section séparée.
Versionné — On sait qui a modifié quoi et quand (idéalement dans Git).
Accessible — Facile à trouver et disponible même si d’autres systèmes sont en panne.
Maintenu — Mis à jour après chaque incident où il a été utilisé.

Règle d’or : si un runbook n’a pas été utilisé ou mis à jour depuis plus de 6 mois, considérez-le comme suspect.

Les 7 qualités d'un bon runbook

Comment créer vos runbooks

Vous n’avez pas besoin de tout documenter d’un coup. Voici une méthode progressive pour construire votre bibliothèque de runbooks.

Méthode pas à pas

Identifier les priorités

Concentrez-vous sur les incidents les plus fréquents ou critiques : quelles alertes reviennent le plus souvent ? Quels incidents ont causé le plus de dégâts ? Listez 5 à 10 situations prioritaires.
Capturer pendant un incident réel

La meilleure façon de créer un runbook : le faire pendant ou juste après un incident. Notez chaque commande, chaque décision, ce qui n’a pas marché.
Structurer le runbook

Le lendemain, organisez vos notes : Symptômes → Prérequis → Procédure → Vérification → Escalade. Ajoutez les étapes implicites qu’un novice ne devinerait pas.
Faire tester par quelqu’un d’autre

Étape cruciale : demandez à un collègue qui ne connaît pas le problème de suivre le runbook. S’il réussit sans poser de questions, c’est gagné.
Publier et rendre accessible

Stockez les runbooks là où tout le monde peut les trouver. L’idéal : un lien direct dans l’alerte de monitoring.
Itérer après chaque utilisation

Après chaque incident : qu’est-ce qui a marché ? Qu’est-ce qui manquait ? Mettez à jour le runbook.

Le cycle de vie d’un runbook

Un runbook n’est jamais terminé — il évolue avec le système qu’il documente.

Cycle de vie d'un runbook

Le cycle vertueux : Incident → Résolution → Postmortem → Mise à jour → Test → Retour au début.

Chaque tour de ce cycle rend le runbook meilleur. Après quelques incidents, vous avez un runbook solid, affiné par l’expérience.

Signe d’alerte : si un runbook n’a pas été modifié depuis plus d’un an, il est probablement obsolète.

Où stocker vos runbooks ?

Solution	Avantages	Inconvénients
Wiki (Confluence, Notion)	Facile à éditer, recherche intégrée	Inaccessible si le réseau est en panne
Git (GitLab, GitHub)	Versionné, revue de code	Moins accessible pour les non-techniques
Dans le monitoring	Lien direct depuis l’alerte	Limité en formatage

Recommandation : stockez dans Git pour le versioning, synchronisez vers le wiki pour l’accessibilité, et ajoutez un lien dans chaque alerte.

N’oubliez pas le plan de secours : gardez une copie des runbooks critiques accessible indépendamment de l’infrastructure principale.

Les anti-patterns à éviter

Le runbook fantôme

Symptôme : « On a des runbooks quelque part… dans le wiki ? Le repo docs ? »

Problème : Un runbook introuvable est pire qu’inexistant — il donne une fausse impression de sécurité.

Solution : Lien direct dans chaque alerte, page d’index centralisée.

Le runbook fossile

Symptôme : « Ce runbook date de 2019, les commandes ne fonctionnent plus. »

Problème : Un runbook obsolète peut être activement dangereux.

Solution : Revue trimestrielle, mise à jour obligatoire après chaque utilisation, date de validation visible en haut du runbook.

Le roman-fleuve

Symptôme : « Le runbook fait 15 pages, je n’ai pas le temps de lire tout ça à 3h du matin ! »

Problème : Sous pression, personne ne lit un document long.

Solution : Procédure en moins d’une page, explications détaillées dans une section séparée « Pour aller plus loin ».

Le copier-coller aveugle

Symptôme : « J’ai copié-collé les commandes sans comprendre, j’ai aggravé le problème. »

Problème : Un runbook n’est pas un script automatique — l’opérateur doit comprendre ce qu’il fait.

Solution : Commentaire explicatif avant chaque commande critique, avertissements visuels (⚠️) pour les commandes dangereuses.

Le runbook secret

Symptôme : « Seule l’équipe infrastructure a accès aux runbooks. »

Problème : Vous recréez le problème de connaissance tacite avec un document au lieu d’une tête.

Solution : Accès en lecture pour toutes les équipes concernées.

L’absence de validation

Symptôme : « Le runbook a été écrit il y a 6 mois, jamais testé. À la première utilisation, la moitié des commandes ne fonctionnent pas. »

Problème : Un runbook non testé est une bombe à retardement.

Solution : Test obligatoire avant publication, « fire drills » périodiques, revue par les pairs.

Anti-patterns des runbooks

Intégrer les runbooks dans votre workflow

Lier runbooks et alertes

Chaque alerte devrait pointer directement vers son runbook. C’est le changement avec le plus d’impact.

Exemple Prometheus/Alertmanager :

groups:
  - name: disk
    rules:
      - alert: DiskSpaceCritical
        expr: disk_used_percent{mountpoint="/var/log"} > 95
        labels:
          severity: critical
        annotations:
          summary: "Disque /var/log plein sur {{ $labels.instance }}"
          runbook_url: "https://wiki.example.com/runbooks/disk-var-log-full"

Runbooks et postmortems

Après chaque incident significatif, le runbook devrait faire partie de l’analyse : était-il utilisé ? À jour ? Suffisant ?

Action obligatoire : créez un ticket de mise à jour du runbook dans les actions correctives du postmortem.

Runbooks et formation

Les runbooks sont un excellent outil de formation pour les nouveaux :

Lecture guidée — Parcourir les runbooks avec un mentor
Simulation — « Wheel of Misfortune » : tirer un incident au sort et le résoudre avec le runbook
Shadowing — Observer un incident réel et suivre le runbook en parallèle
Autonomie supervisée — Gérer un incident seul avec un expert joignable
Contribution — Améliorer les runbooks basé sur son expérience de novice

Checklists pratiques

Pour commencer (minimum viable)

Lister les 5 alertes les plus fréquentes
Créer un runbook pour chacune
Stocker dans un emplacement accessible à tous
Ajouter le lien dans chaque alerte (runbook_url)
Tester chaque runbook en environnement de test
Identifier un responsable par runbook
Planifier une revue trimestrielle

Pour une organisation mature

Tous les incidents critiques ont un runbook
Runbooks versionnés dans Git
Mise à jour obligatoire après chaque utilisation
Revue par un pair avant publication
Intégration dans le processus de postmortem
Formation des nouveaux via les runbooks
Tests périodiques (« fire drills »)
Procédures de rollback incluses

À retenir

Vous avez lu beaucoup d’informations dans ce guide. Voici l’essentiel à garder en tête — les 8 points fondamentaux qui résument tout ce que vous devez savoir sur les runbooks :

Un runbook est une recette, pas un cours théorique — Il prescrit les actions à mener, étape par étape, pour résoudre un problème précis. Ce n’est pas une explication de l’architecture ou une documentation du système. Quand vous lisez un runbook, vous devez pouvoir agir, pas apprendre.
Sans runbook, la connaissance reste dans les têtes — Chaque expert qui garde son savoir pour lui est un point de défaillance unique humain. Quand cette personne n’est pas disponible (vacances, maladie, départ), vous êtes vulnérable. Les runbooks éliminent ce risque en rendant la connaissance accessible à tous.
Le stress dégrade la prise de décision — À 3h du matin, fatigué et stressé, votre cerveau ne fonctionne pas comme en plein jour. Un runbook compense en fournissant une procédure à suivre mécaniquement. Pas besoin de réfléchir sous pression — il suffit de lire et d’exécuter.
Un bon runbook est actionnable, testé et maintenu — Ce n’est pas une documentation générale, c’est un guide d’action précis. Il doit avoir été testé en conditions réelles (ou simulées). Et s’il n’a pas été utilisé ou mis à jour depuis 6 mois, considérez-le comme suspect.
Chaque alerte devrait pointer vers son runbook — C’est le changement avec le meilleur retour sur investissement. Quand l’opérateur reçoit une alerte, le lien vers le runbook est là, dans le message. Zéro recherche, zéro temps perdu.
Le cycle vertueux : incident → résolution → mise à jour — Chaque incident est une occasion d’améliorer le runbook. Ce qui n’a pas marché est corrigé, ce qui manquait est ajouté. Après quelques incidents, vous avez un runbook solid, affiné par l’expérience.
Tester régulièrement — Un runbook non testé est une fausse sécurité. Vous pensez être protégé, mais le jour où vous en avez vraiment besoin, vous découvrez qu’il ne fonctionne plus. Testez vos runbooks comme vous testez vos sauvegardes : régulièrement et avant d’en avoir besoin.
Concis pour l’action, détaillé ailleurs — La procédure tient sur une page. Les explications détaillées, le « pourquoi », l’architecture… tout ça va dans une section séparée ou dans la documentation. Pendant un incident, l’opérateur n’a pas le temps de lire un roman.

Prochaine étape concrète : identifiez l’alerte qui s’est déclenchée le plus souvent le mois dernier. Créez un runbook pour cette alerte. Ajoutez le lien dans l’alerte. Félicitations, vous venez de faire le premier pas vers une meilleure résilience opérationnelle.

Liens internes

Travail ingrat — Réduire les corvées répétitives
Patch management — Automatiser les mises à jour

Sources et références

Site Reliability Engineering (Google) ↗ — Chapitre sur le troubleshooting efficace
Emergency Response (Google SRE) ↗ — Gestion des urgences
Being On-Call (Google SRE) ↗ — Organisation des astreintes
CIS Controls ↗ — Bonnes pratiques de sécurité
NIST Cybersecurity Framework ↗ — Cadre de référence