Service Overview : la carte d'identité du service

Nouveau dans l’équipe, vous devez intervenir sur le service “API Payments”. Première question : c’est quoi ce service, exactement ?

Sans Service Overview, vous passez 2 heures à chercher des infos éparpillées dans le wiki, le README, Slack et les dashboards. Avec un bon Overview, vous comprenez le service en 15 minutes : son rôle, son architecture, ses dépendances et qui contacter.

Le concept de Service Overview vient des pratiques Site Reliability Engineering (SRE) popularisées par Google. Dans leur approche, chaque service en production doit avoir une documentation de référence qui permet à n’importe quel ingénieur d’intervenir rapidement, même sans connaissance préalable du service.

Ce guide vous apprend à créer ce document essentiel que chaque service devrait avoir.

Qu’est-ce qu’un Service Overview ?

L’analogie de la carte d’identité

Une carte d’identité contient vos informations essentielles : nom, photo, date de naissance, adresse. En un coup d’œil, on sait qui vous êtes.

Le Service Overview est la carte d’identité de votre service.

Il répond aux questions fondamentales :

• Quoi ? — Que fait ce service ?
• Pourquoi ? — Quel problème résout-il ?
• Comment ? — Quelle architecture, quelles dépendances ?
• Qui ? — Qui le maintient, qui contacter ?
• Quand ? — Quel SLA, quelle criticité ?

Ce que ce n’est pas

Service Overview	≠ Ce que ça n’est pas
Vue d’ensemble	Documentation exhaustive
Référence rapide	Tutoriel d’apprentissage
Informations stables	Procédures opérationnelles
Point d’entrée	Runbooks détaillés

Règle d'or

Un Service Overview doit pouvoir être lu en 15 minutes par quelqu’un qui ne connaît pas le service. S’il faut plus, c’est trop long.

Pourquoi c’est indispensable

Les trois moments où vous en avez besoin

1. Onboarding nouveau membre

Premier jour : “Tu vas travailler sur l’API Payments.”

• Sans Overview : 3 jours à harceler les collègues
• Avec Overview : 1 heure de lecture, questions ciblées ensuite

2. Incident sur un service inconnu

3h du matin, alerte sur un service que vous ne gérez pas d’habitude.

• Sans Overview : “C’est quoi ce truc ? Qui appeler ?”
• Avec Overview : contacts, architecture, runbooks liés → intervention rapide

3. Audit de sécurité / conformité

“Expliquez-nous l’architecture de ce service et ses flux de données.”

• Sans Overview : réunion de 2h pour reconstituer les infos
• Avec Overview : “Voici le document, questions ?”

Production Readiness Review (PRR)

Chez Google, le Service Overview s’inscrit dans le processus de Production Readiness Review. Avant qu’un service soit pris en charge par les équipes SRE, il doit démontrer sa maturité opérationnelle. Le Service Overview est l’une des pièces maîtresses de cette revue.

Les critères évalués lors d’une PRR incluent :

• Documentation complète : le service est-il compréhensible sans aide ?
• Observabilité : métriques, logs, traces sont-ils en place ?
• Résilience : que se passe-t-il si une dépendance tombe ?
• Contacts : qui appeler en cas d’incident à 3h du matin ?

Référence

Le livre Site Reliability Engineering de Google détaille le processus PRR dans le chapitre “Evolving SRE Engagement Model”. C’est une lecture recommandée pour comprendre l’importance de la documentation opérationnelle.

Structure d’un Service Overview

Voici un exemple de structure simple et efficace :

# Service : [Nom]

## Identité
- Owner, criticité, SLA

## Vue d'ensemble
- Ce que fait le service (2-3 phrases)
- Utilisateurs / clients

## Architecture
- Diagramme simple
- Composants principaux
- Dépendances

## Données
- Types de données traitées
- Stockage (DB, cache)
- Sensibilité (PII, etc.)

## Opérations
- Déploiement
- Monitoring
- Alertes principales

## Liens
- Runbooks
- Dashboards
- Repo code

## Contacts
- Équipe owner
- Oncall
- Escalade

Et un exemple concret :

# Service : API Payments

**Owner** : @team-billing
**Criticité** : Tier 1 (revenue-impacting)
**SLA** : 99.9% uptime

## Vue d'ensemble

L'API Payments traite toutes les transactions de paiement par
carte bancaire et PayPal. Elle est appelée par le checkout web
et l'app mobile lors de la finalisation d'une commande.

**Chiffres clés** :
- 500K transactions/jour
- Latence p99 : 200ms
- Revenue : critique (100% des revenus transitent ici)

## Architecture

```text
[Checkout Web/Mobile]
        |
        v
[Load Balancer]
        |
        v
[API Payments] (3 instances K8s)
        |
    +---+---+
    |       |
    v       v
[Stripe] [PayPal]
    |
    v
[DB Payments (PostgreSQL)]
```

**Composants** :
- API Gateway : Kong
- Runtime : Node.js 18
- Database : PostgreSQL 14 (RDS)
- Cache : Redis (sessions)

**Dépendances externes** :
- Stripe API (paiements CB)
- PayPal API (paiements PayPal)

## Données

| Type | Sensibilité | Stockage |
|------|-------------|----------|
| Transaction ID | Interne | DB Payments |
| Montant | Interne | DB Payments |
| Token carte | Jamais stocké | Stripe |
| Email client | PII | DB Users (autre service) |

**RGPD** : pas de stockage de données carte (tokenisation Stripe)

## Opérations

**Déploiement** :
- CI/CD : GitHub Actions → ArgoCD
- Stratégie : Canary 10% puis 100%
- Rollback : `helm rollback api-payments`

**Monitoring** :
- Dashboard : Grafana - API Payments (https://grafana.example.com/d/payments)
- Logs : Kibana - payments-* (https://kibana.example.com/payments)

**Alertes principales** :
- `payments_error_rate > 1%` → PagerDuty P1
- `payments_latency_p99 > 500ms` → PagerDuty P2
- `payments_db_connections > 80%` → Slack #payments-alerts

## Liens

| Ressource | Lien |
|-----------|------|
| Code | https://github.com/company/api-payments |
| Runbook déploiement | /runbooks/payments-deploy |
| Runbook incident | /runbooks/payments-incident |
| Dashboard | https://grafana.example.com/d/payments |
| API Docs | /api/payments |

## Contacts

| Rôle | Contact |
|------|---------|
| Équipe owner | @team-billing |
| Oncall | #payments-oncall (Slack) |
| Tech Lead | @alice |
| PM | @bob |
| Escalade | @vp-engineering |

Créer un Service Overview : pas à pas

La création d’un Service Overview prend généralement entre 2 et 4 heures pour un service existant. Pour un nouveau service, intégrez cette étape dès le début du développement — c’est plus facile de documenter au fur et à mesure que de reconstituer après coup.

1. Collecter les informations

   Commencez par rassembler tout ce qui existe déjà. Ne réinventez pas, consolidez.

   Sources typiques :

   • README du repository (souvent incomplet mais point de départ)
   • Wiki d’équipe ou Confluence (attention aux pages obsolètes)
   • Conversations Slack archivées (cherchez les questions récurrentes)
   • Dashboards Grafana/Datadog (révèlent les métriques clés)
   • Runbooks existants (si vous avez de la chance)
   • ADR (Architecture Decision Records) si votre équipe en fait

   Astuce : Posez la question “Comment tu expliquerais ce service à quelqu’un qui arrive ?” aux membres de l’équipe. Les réponses révèlent ce qui est vraiment important.

   Durée estimée : 2h

2. Rédiger l’identité et la vue d’ensemble

   Les 5 premières lignes sont les plus importantes. Un lecteur doit comprendre l’essentiel en 30 secondes.

   Test : montrez ces 5 lignes à quelqu’un d’externe. Comprend-il ?

3. Créer le diagramme d’architecture

   Le diagramme est souvent la partie la plus consultée. Restez simple : boîtes et flèches, pas d’UML complexe.

   Formats recommandés (par ordre de facilité de maintenance) :

   • ASCII art : Directement dans le Markdown, versionnée avec le code
   • Mermaid : Rendu automatique dans GitHub/GitLab
   • Excalidraw : Aspect “dessiné à la main”, fichiers JSON versionnables
   • Draw.io : Plus complet, export PNG/SVG

   Évitez les images binaires (PNG/JPG) stockées sans source : impossibles à modifier sans refaire depuis zéro.

   Niveau de détail : Montrez les composants principaux et leurs interactions. Un nouveau doit comprendre “qui parle à qui” en 30 secondes.

4. Documenter les dépendances

   Distinguez clairement :

   • Dépendances internes : autres services de votre organisation
   • Dépendances externes : APIs tierces (Stripe, AWS, etc.)
   • Dépendances infrastructure : bases de données, cache, queues

   Pour chaque dépendance, documentez :

   • Impact si indisponible : service dégradé ou totalement down ?
   • Timeout configuré : évite les cascades de pannes
   • Fallback : existe-t-il un mode dégradé ?

   C’est cette section qui sauve lors des incidents en cascade.

5. Lister les opérations essentielles

   Pas les procédures complètes (c’est le runbook), juste :

   • Comment déployer (1 ligne)
   • Où voir les métriques
   • Quelles alertes existent

6. Ajouter les contacts

   Qui appeler à 3h du matin ? C’est LA question.

   Mettre des liens Slack/email, pas juste des noms.

7. Faire relire par un “étranger”

   Quelqu’un qui ne connaît pas le service doit relire.

   S’il a des questions → le doc n’est pas complet.

8. Publier et lier

   • Lier depuis le README du repo
   • Lier depuis les alertes PagerDuty
   • Ajouter à l’index des services

Maintenir le Service Overview

Un Service Overview obsolète est pire qu’aucun document : il induit en erreur. La maintenance est donc aussi importante que la création initiale.

Le problème de la documentation morte

Selon une étude de Cortex.io, les checklists de production readiness deviennent rapidement obsolètes dans les startups en croissance. Les services créés il y a 6 mois ne respectent plus les standards actuels, et personne ne met à jour.

Solution : Intégrer la mise à jour dans les processus existants plutôt que de compter sur la bonne volonté.

Quand mettre à jour ?

Événement	Action	Déclencheur
Changement architecture	Mettre à jour le diagramme	PR review
Nouvelle dépendance	Ajouter à la liste	PR review
Changement SLA	Mettre à jour l’identité	Revue trimestrielle
Nouveau dashboard	Ajouter aux liens	Après création
Changement d’équipe owner	Mettre à jour les contacts	Offboarding

Intégrer dans la DoD

## PR Checklist (si changement significatif)

- [ ] Service Overview à jour
  - [ ] Diagramme architecture reflète le changement
  - [ ] Dépendances mises à jour
  - [ ] Liens valides

Anti-patterns Service Overview

Erreurs fréquentes à éviter

Ces erreurs rendent le Service Overview inutilisable. Surveillez-les lors de vos reviews.

Anti-pattern	Problème	Solution
50 pages	Personne ne lit	Max 2-3 pages
Pas de diagramme	Impossible à visualiser	Toujours un schéma
Contacts obsolètes	Appel de la mauvaise personne	Review à chaque départ
Copier-coller du code	Obsolète en 1 semaine	Liens vers le code
Jargon non expliqué	Nouveau perdu	Glossaire ou explications

Template à copier

# Service : [NOM]

**Owner** : @team-xxx
**Criticité** : Tier 1/2/3
**SLA** : XX.X%

## Vue d'ensemble

[2-3 phrases : ce que fait le service, pour qui]

**Chiffres clés** :
- [Métrique 1]
- [Métrique 2]

## Architecture

```text
[Diagramme ASCII simple]
```

**Composants** :
- [Composant 1] : [rôle]
- [Composant 2] : [rôle]

**Dépendances** :
- [Dépendance 1] : [impact si down]
- [Dépendance 2] : [impact si down]

## Opérations

**Déploiement** : [1 ligne]
**Monitoring** : [lien dashboard]
**Alertes** : [liste principales]

## Liens

| Ressource | Lien |
|-----------|------|
| Code | [lien] |
| Runbooks | [lien] |
| Dashboard | [lien] |

## Contacts

| Rôle | Contact |
|------|---------|
| Oncall | [lien Slack] |
| Tech Lead | @xxx |
| Escalade | @xxx |

Outils et catalogues de services

Pour les organisations avec de nombreux services, maintenir des Service Overviews individuels devient complexe. Des outils de Software Catalog centralisent cette information.

Backstage (Spotify)

Backstage ↗ est un portail développeur open source créé par Spotify. Il centralise la documentation, les owners, les dépendances et les métriques de tous les services dans un catalogue unifié.

Chaque service est décrit par un fichier catalog-info.yaml versionné avec le code :

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: api-payments
  description: API de traitement des paiements
  annotations:
    grafana/dashboard-selector: "payments"
spec:
  type: service
  lifecycle: production
  owner: team-billing
  dependsOn:
    - component:stripe-integration
    - resource:payments-db

Autres solutions

Outil	Type	Points forts
Backstage	Open source	Extensible, large communauté
Cortex	SaaS	Scorecards, production readiness automatisée
OpsLevel	SaaS	Focus sur la maturité des services
Port	SaaS	Internal Developer Portal complet

Commencez simple

Si vous débutez, un simple dossier docs/ avec des fichiers Markdown par service suffit. Migrez vers un catalogue centralisé quand vous dépassez 20-30 services.

Ressources externes

• Google SRE Book - Production Readiness Review ↗ — Le chapitre de référence sur les PRR
• Google SRE Workbook - SLO Document Example ↗ — Exemple de documentation SLO
• Backstage Software Catalog ↗ — Documentation officielle Backstage
• TechTarget - SRE Documentation Best Practices ↗ — Introduction aux bonnes pratiques

Guides complémentaires

Runbooks Procédures opérationnelles étape par étape

Postmortems Documenter et apprendre des incidents

Documentation opérationnelle Structurer votre documentation technique