Documentation d’architecture exploitable : écrire une note qui aide vraiment le run après le déploiement

Une documentation d’architecture peut être très propre le jour de la livraison et inutile trois semaines plus tard. Un schéma, quelques choix de composants et une liste de ressources ne suffisent pas toujours à exploiter un système. Le run a besoin de savoir comment valider, où regarder quand ça casse, quelles limites ont été acceptées et quelles décisions ne doivent pas être inversées sans revue.

Le scénario pris ici est celui d’une architecture cloud ou infrastructure livrée à une équipe d’exploitation : réseau privé, DNS, frontal HTTPS, automatisation, sauvegarde ou intégration Linux. L’objectif n’est pas de produire un document long. L’objectif est de produire une note qui reste utile après le déploiement.

Écrire le problème avant la solution

Une bonne note commence par le besoin opérationnel, pas par le nom des services. Si la première phrase dit seulement que l’architecture utilise Application Gateway, Private Endpoint ou AWX, elle manque le contexte. Il faut expliquer le flux ou le problème traité.

Contexte utile
Une application métier doit être publiée vers un partenaire externe.
L'appel doit être authentifié par certificat client.
Le backend reste privé.
L'équipe run doit pouvoir diagnostiquer DNS, TLS, WAF et santé backend séparément.

Contexte faible
Mise en place d'un Application Gateway avec WAF.

Cette différence change la suite du document. Le premier contexte prépare les validations et les modes de panne. Le second ne dit presque rien sur l’exploitation.

Documenter les décisions et les non-décisions

Une architecture contient toujours des alternatives non retenues. Les écrire évite de refaire le même débat pendant un incident ou une évolution. Une décision utile explique le choix, sa raison et sa limite.

Décision
Utiliser Application Gateway comme point d'entrée HTTPS.

Raison
Le besoin principal est la publication contrôlée d'une application web avec listener dédié, mTLS, WAF et probe backend.

Non retenu
API Management n'est pas utilisé car le besoin ne porte pas sur le cycle de vie API, les produits, les subscriptions ou la transformation de payload.

Limite
Si le besoin évolue vers de la gouvernance API, cette décision doit être revue.

Ce format est court, mais il évite les documents qui décrivent seulement l’état final sans expliquer pourquoi il existe.

Ajouter les commandes de validation

Une documentation exploitable doit permettre de prouver que le système fonctionne. Les commandes ne doivent pas être décoratives. Elles doivent valider les points critiques : résolution DNS, certificat, backend health, identité, sauvegarde, job d’automatisation ou restauration.

nslookup app.example.com
curl -vk https://app.example.com/health

az network application-gateway show-backend-health -g rg-network-hub-prod -n agw-internet-prod-001 -o table

id user@example.local
sssctl domain-status example.local

Ces commandes doivent être adaptées au sujet, mais l’intention est constante : donner au run un moyen de vérifier une hypothèse. Une commande sans résultat attendu est moins utile. Il faut préciser ce qu’un succès ou un échec signifie.

Écrire les modes de panne probables

Les modes de panne sont souvent plus utiles qu’un schéma complet. Ils indiquent quoi regarder quand un symptôme apparaît. Il ne s’agit pas d’énumérer toutes les erreurs possibles, mais les pannes prévisibles liées au design.

Symptôme : le client reçoit 502
Vérifier backend health Application Gateway
Vérifier probe, hostname backend et certificat TLS
Lire logs d'accès et WAF sur la même période

Symptôme : le service PaaS répond publiquement
Vérifier publicNetworkAccess
Vérifier résolution DNS depuis la source testée
Confirmer que le test n'utilise pas un resolver externe

Symptôme : un job AWX modifie trop de machines
Vérifier inventaire associé au template
Vérifier variables launch-time
Vérifier garde-fous dans le playbook

Ce bloc donne de la valeur immédiatement. Il transforme l’expérience de conception en aide au diagnostic.

Décrire le rollback ou le chemin de retour

Tout changement n’a pas un rollback simple, mais il doit y avoir une stratégie. Réactiver temporairement un accès public, revenir à un ancien backend setting, restaurer une VM, désactiver un job AWX ou revenir à une version de playbook sont des décisions différentes. Les écrire avant l’incident réduit l’improvisation.

Changement : fermeture de l'accès public Function
Retour possible : réactiver publicNetworkAccess temporairement
Condition : validation sécurité et durée limitée
Vérification après retour : test public et test privé documentés

Changement : nouveau backend setting Application Gateway
Retour possible : réassocier l'ancienne règle au précédent backend setting
Condition : ancien objet conservé pendant la fenêtre de changement

Le rollback doit aussi indiquer ce qui ne revient pas automatiquement : données modifiées, secrets tournés, caches, DNS propagé ou configurations appliquées par automation.

Garder le document vivant mais borné

Une note exploitable doit évoluer avec les changements réels, mais elle ne doit pas devenir un wiki infini. Les sections stables sont le contexte, les décisions, le schéma de flux, les validations, les modes de panne et le rollback. Les détails trop volatils peuvent pointer vers des inventaires ou outils de référence.

Structure recommandée
1. Contexte et objectif
2. Flux attendu
3. Décisions et limites
4. Composants et responsabilités
5. Validations opérationnelles
6. Modes de panne probables
7. Rollback ou chemin de retour
8. Historique court des changements importants

Cette structure reste lisible pour un article, une note interne ou un runbook. Elle force surtout à documenter ce qui aide après livraison.

Exemple de fiche de passage au run

Pour rendre la note vraiment exploitable, il faut finir par une fiche courte que l’équipe run peut utiliser sans relire tout le dossier projet. Cette fiche ne remplace pas l’architecture, mais elle résume les contrôles qui comptent le jour où l’application est en production.

Service : portail partenaire
Point d'entrée : app.example.com via Application Gateway
Backend : application privée dans spoke applicatif
DNS critique : app.example.com, backend.internal.example.com
Validation quotidienne : backend health sain, certificat valide, WAF sans blocage anormal
Incident 502 : vérifier probe, hostname backend, certificat et logs WAF
Changement sensible : modification listener, backend setting, policy WAF ou zone DNS
Retour arrière : ancien backend setting conservé pendant la fenêtre de changement
Contact run : équipe plateforme
Contact applicatif : équipe produit concernée

Cette fiche donne du relief au document. Elle montre ce qui doit être connu à froid, avant l’incident : noms, dépendances, validations, symptômes, rollback et responsabilités.

Conclusion

Une documentation d’architecture utile n’est pas celle qui décrit le plus de composants. C’est celle qui aide une équipe à comprendre le flux, valider l’état, diagnostiquer les pannes et prendre une décision de retour arrière. Elle doit garder les décisions, les limites et les preuves près du design.

Le bon niveau de détail est celui qui reste exploitable sous pression. Un schéma peut aider, mais les commandes de validation, les modes de panne, les décisions non retenues et une fiche de passage au run font souvent la différence le jour où le système ne se comporte plus comme prévu.