Diagrammes d'architecture de style AWS
Vue d'ensemble
Produisez des diagrammes qui suivent les conventions des diagrammes d'architecture de référence AWS : noms de services précis, limites de compte/Région/VPC étiquetées, étiquettes de flux courtes, et un canevas épuré. « Style AWS » décrit ces conventions ; il n'exige pas en soi les icônes officielles AWS ou Graphviz.
Mermaid et Graphviz DOT sont des formats de création équivalents. Mermaid convient souvent pour la documentation inline, adaptée au thème et révisable textuellement ; DOT convient souvent pour les actifs d'icônes AWS locaux exacts, une composition contrôlée, et des SVG/PNG prêts pour la présentation. Utilisez l'un d'eux lorsqu'il satisfait l'ensemble du contrat de livraison et les deux lorsque des audiences ou artefacts distincts rendent la maintenance supplémentaire utile.
Quand utiliser
Utilisez cette compétence pour les diagrammes d'architecture AWS, de topologie, de contexte système ou de flux de données basés sur des preuves. Ne l'utilisez pas pour un visuel non AWS ou lorsqu'un tableau seul communique plus clairement les faits demandés.
Rationalisations courantes
- « Le style AWS signifie DOT » ignore les rendus Mermaid qui remplissent le contrat réel.
- « Les deux formats sont plus sûrs » crée un coût de synchronisation sans deux consommateurs nommés.
- « Le service se connecte probablement ici » n'est pas une preuve pour une arête.
Drapeaux rouges
Arrêtez-vous et résolvez les ressources ou relations non prises en charge, un rendu cible ambigu, des droits ou actifs d'icônes manquants, des preuves sources conflictuelles, ou une Région demandée en dehors du périmètre autorisé avant de dessiner ou d'interroger l'infrastructure live.
La règle qui prime sur l'esthétique
Ne dessinez que ce que la source établit. Chaque nœud, arête, limite, Région et protocole doit pouvoir être retracé à quelque chose de réel — Terraform, CloudFormation, CDK, configuration déployée, ou une déclaration écrite d'un propriétaire. Un diagramme est un artefact de preuve qui se trouve être visuel.
N'ajoutez jamais un service, une connexion, une zone de disponibilité, un VPC ou une Région parce que l'image semble déséquilibrée sans cela. Si la source n'établit pas une limite, laissez-la de côté ; un diagramme honnête et clairsemé est meilleur qu'un diagramme décoratif complet. Lorsque quelque chose est déployé mais désactivé, indiquez-le sur le nœud (WEB_PUSH_ENABLED=false, « Déployé, désactivé pour la publication ») plutôt que de le dessiner comme s'il était actif, et marquez ce qu'une autre équipe possède afin qu'un lecteur ne pense pas que vous le contrôlez.
Indiquez la provenance dans le diagramme lui-même — un sous-titre nommant la source, par exemple « tracé à <iac-dir>/*.tf à <révision> » ou « inventaire live en lecture seule, <date> » — et répétez-le dans un commentaire d'en-tête dans le source DOT.
Nommez la ressource, pas seulement le service
Une icône de service seule n'identifie rien. Un glyphe DynamoDB magenta étiqueté « Opérations » pourrait être une table, un flux ou un index, et un lecteur n'a aucun moyen de le trouver dans la console. Chaque nœud énonce trois faits :
- Comment il s'appelle dans AWS. Le nom réel déployé —
acme-orders-events, pas un alias convivial comme « Commandes ». Écrivez un ID de compte comme<compte>plutôt que les chiffres ; ne mettez jamais un secret, un jeton ou un point de terminaison dans un diagramme. - Quel type de ressource c'est. Écrit, en gris, sous le nom : « Table DynamoDB », « Bucket S3 », « Fonction Lambda », « API Gateway HTTP API », « WAFv2 web ACL », « Identité e-mail SES v2 ».
- À quoi ça sert. Une ligne, et seulement là où un lecteur ne pourrait pas le déduire.
Pour la sortie Graphviz, utilisez une icône de ressource là où AWS en publie une — Res_Amazon-DynamoDB_Table, Res_Amazon-Simple-Storage-Service_Bucket, Res_AWS-Lambda_Lambda-Function — et une icône de service (Arch_) pour tout le reste. L'icône renforce l'identité ; elle ne doit jamais être la seule chose qui la porte, car une icône n'est pas lisible en niveaux de gris, à la taille d'une vignette, ou par un lecteur d'écran.
Choisissez le format en fonction des exigences
Il n'y a pas de gagnant global et pas de format par défaut. Honorez un format source explicitement demandé à moins qu'il n'entre en conflit avec un autre critère d'acceptation. Sinon, comparez les besoins de livraison réels :
| Exigence | Mermaid tend à mieux convenir | Graphviz DOT tend à mieux convenir |
|---|---|---|
| Révision du dépôt | Rendu Markdown inline, diffs textuels compacts | Source textuelle révisable plus artefacts rendus séparément |
| Type de diagramme | Séquence, flux, état, dépendance, et vues d'architecture simples | Topologie dense, limites imbriquées, et graphes nécessitant un routage d'arêtes délibéré |
| Visuels AWS | Noms, limites, couleurs de style AWS, ou packs d'icônes fournis par le rendu | Actifs d'icônes AWS publiés localement dans le dépôt |
| Mise en page | Mise en page réactive gérée par le rendu et adaptation au thème | Rangs, ports, clusters, espacement, et composition fixe précis |
| Livraison | Documentation qui doit s'afficher là où elle est écrite | SVG/PNG contrôlés pour les présentations, documents et surfaces de présentation |
| Outillage | Le rendu cible prend déjà en charge la syntaxe et la version Mermaid requises | Graphviz et les actifs locaux requis sont disponibles dans l'environnement de construction ou de création |
Si le contenu demandé est en fait tabulaire, utilisez un tableau Markdown plutôt que de le transformer en image. Pour un échange ordonné de participants, sequenceDiagram de Mermaid est généralement le choix naturel ; c'est un avantage du type de diagramme, pas une préférence générale pour Mermaid.
Mermaid prend en charge les diagrammes d'architecture et les packs d'icônes configurables, mais on ne peut pas supposer qu'un rendu hébergé fournisse des actifs AWS locaux au dépôt, un enregistrement de pack personnalisé, ou la même version de Mermaid qu'un rendu local contrôlé. Graphviz peut charger des actifs d'images locaux directement, c'est donc le choix fiable lorsque des actifs d'icônes exacts et une composition exportée fixe sont des critères d'acceptation, pas simplement parce que la demande dit « style AWS ».
Comptez les compromis des deux côtés. Mermaid peut varier selon les versions du rendu, les packs d'icônes disponibles et les thèmes hôtes. DOT ajoute une étape de rendu et des artefacts générés qui doivent rester synchronisés avec le source modifiable. Sélectionnez le format dont les coûts correspondent au dépôt et à la destination plutôt que de traiter les forces de l'un ou l'autre outil comme universelles.
Si le support du rendu, la fidélité des icônes, la composition fixe, ou les fichiers de sortie attendus changeraient matériellement le résultat et que la demande est ambiguë, clarifiez le contrat de livraison. Sinon, sélectionnez le format qui satisfait les exigences connues avec le moins de mécanismes spécifiques au projet.
Lorsque Mermaid est sélectionné, conservez les règles de preuve, de provenance, de nommage des ressources et d'accessibilité ci-dessus, validez le source dans son rendu cible, et arrêtez-vous avant le workflow spécifique à Graphviz ci-dessous.
Quand les deux formats sont justifiés
Produisez Mermaid et DOT lorsqu'ils satisfont des exigences réelles différentes, comme une révision inline du dépôt plus une sortie de présentation exacte avec icônes AWS. La double livraison n'est pas automatiquement meilleure : elle n'est justifiée que lorsque les deux artefacts ont un consommateur nommé ou un critère d'acceptation.
Aucun source n'est canonique par défaut. Dérivez les deux du même inventaire vérifié de ressources et de relations, portez la même provenance, et vérifiez que les nœuds, arêtes, limites, Régions, propriété et incertitudes concordent. Un format peut ajouter une structure spécifique à la présentation sans modifier l'architecture qu'il prétend représenter. Nommez un format comme faisant autorité uniquement lorsque l'utilisateur ou la politique du dépôt lui attribue explicitement ce rôle.
Pour une carte système complète exceptionnellement dense qui nécessite des icônes AWS exactes, une composition fixe, ou un placement de connecteur au niveau des ports, DOT avec ses SVG et PNG peut servir comme artefact de présentation et d'icônes AWS. Un rendu Mermaid peut servir de compagnon maintenable et révisable inline lorsque cela est également requis. Pour un flux ciblé sans ces exigences spécifiques à DOT, Mermaid seul peut satisfaire le contrat. Ce sont des choix basés sur les exigences, pas une raison de produire les deux formats pour chaque diagramme.
Workflow Mermaid
1. Sélectionnez le type de diagramme Mermaid
Utilisez architecture-beta ou un organigramme pour l'architecture et la topologie, un sequenceDiagram pour les échanges ordonnés, et un diagramme d'état uniquement pour les transitions d'état réelles. Confirmez que le rendu cible prend en charge la syntaxe sélectionnée et tout pack d'icônes ; ne supposez pas que GitHub, un site de documentation et un CLI Mermaid local exécutent la même version ou configuration. Lorsque vous utilisez des symboles Iconify, conservez le nom complet de la ressource AWS et le type en texte ; une icône ne doit jamais être le seul identifiant de ressource.
2. Encodez l'inventaire vérifié
Représentez les limites de compte AWS, Région, VPC, zone de disponibilité, sous-réseau et propriété uniquement lorsque les preuves les établissent. Utilisez des noms et types de ressources complets, des arêtes courtes étiquetées, et des annotations visibles pour les relations autorisées ou inférées. Conservez la provenance dans le Markdown adjacent et, lorsque la syntaxe le permet, dans un commentaire source.
3. Rendez et inspectez dans l'environnement cible
Utilisez la commande Mermaid ou la construction de documentation épinglée du dépôt. Validez le bloc délimité exact ou le source .mmd qui sera livré, puis inspectez le résultat rendu à sa largeur et son thème prévus. Vérifiez les étiquettes tronquées, les arêtes qui se chevauchent, les icônes ou syntaxes non prises en charge, le contraste inaccessible, et la dérive sémantique par rapport à l'inventaire vérifié. Corrigez le source modifiable et rendez à nouveau jusqu'à ce qu'il soit lisible.
Enregistrez explicitement les packs d'icônes non intégrés. Pour Mermaid CLI, un rendu de symbole AWS reproductible peut utiliser :
mmdc --iconPacks '@iconify-json/logos' \
-i system-context-aws.mmd -o system-context-aws.svg -b white
Considérez un repli ? comme un rendu échoué, pas une dégradation cosmétique. Le support des packs d'icônes peut varier selon la version Mermaid et le rendu de mise en page ; vérifiez la sortie réelle visuellement et structurellement. Si un rendu pris en charge perd les icônes enregistrées, utilisez un autre rendu pris en charge qui les conserve et documentez le compromis de mise en page. Ne revendiquez pas la portabilité inline à moins que l'hôte cible n'enregistre également le pack requis.
4. Livrez les artefacts requis
Gardez Mermaid inline lorsque c'est le contrat du dépôt. Lorsque des sorties SVG ou PNG autonomes sont requises, rendez-les de manière déterministe avec la version Mermaid épinglée du dépôt et documentez la commande de reproduction.
Workflow Graphviz
1. Établissez l'architecture à partir de la source
Lisez l'IaC et inventoriez ce qui existe réellement avant de dessiner quoi que ce soit. Trouvez le répertoire où ce projet le conserve — infra/, terraform/, deploy/, une application CDK — plutôt que de supposer une structure :
iac_dir=infra # quoi que ce soit que ce dépôt utilise réellement
grep -hoE '^resource "aws_[a-z0-9_]+"' "$iac_dir"/*.tf | sort | uniq -c | sort -rn
Ensuite, extrayez les spécificités qui rendent les arêtes réelles et les noms qui vont sur les nœuds : noms de fonctions, noms de tables, noms de buckets, règles d'événements et leurs planifications, notifications S3, autorisateurs, et toute autorisation inter-compte ou inter-stack. Résolvez les noms à travers leurs variables et locales jusqu'à la valeur réellement déployée. Notez la Région à partir de la variable qui la définit, pas par hypothèse.
1b. Quand il n'y a pas d'IaC, ou que l'IaC ne couvre qu'une partie du domaine
Parfois, la chose à diagrammer est un compte en cours d'exécution pour lequel personne n'a Terraform, ou le Terraform ne couvre qu'une fraction de ce qui est déployé. Alors la source est le compte live, en lecture seule, et le diagramme doit être explicite sur le fait que c'est ce qu'il est.
Commencez par un prédicat de balise plutôt que par un balayage service par service, car c'est le seul moyen de délimiter « ce qui appartient à ce système » :
aws resourcegroupstaggingapi get-resources --region <region> \
--tag-filters 'Key=<cle>,Values=<v1>,<v2>'
Plusieurs clés de balise nécessitent chacune une requête distincte, unies par ARN ensuite — passer deux clés dans une seule requête applique ET, supprimant silencieusement tout ce qui ne porte qu'une seule d'entre elles. Enregistrez le nombre et la date résultants ; c'est un instantané, pas un fait.
L'API de balisage ne renvoie pas tous les types de ressources, et les balises ne sont pas la propriété. Donc la requête de balise vous donne l'ensemble des nœuds, et les relations proviennent des API qui les modélisent réellement :
| Pour établir | Lire |
|---|---|
| Câblage d'entrée | elbv2 describe-load-balancers, describe-target-groups |
| Quels chemins sont autorisés | ec2 describe-security-groups, describe-vpcs |
| Ce qu'un niveau de calcul peut appeler | iam get-instance-profile, puis get-policy-version |
| Forme et répliques du niveau de données | rds describe-db-instances, elasticache describe-* |
| Câblage asynchrone | politiques de redirection des files d'attente, notifications S3, règles d'événements |
Résolvez chaque CIDR que vous trouvez en un VPC nommé avant de le dessiner ; un CIDR 10.16.0.0/16 non résolu sur un diagramme ne dit rien à un lecteur.
1c. Dites sur quel type de preuve chaque arête repose
C'est le plus important lors de la lecture d'un compte live, où il est tentant de tracer une ligne parce que deux ressources partagent un préfixe de nom. Séparez les classes visuellement et définissez-les dans le diagramme et son texte :
- Câblage que AWS lui-même signale — les cibles d'un groupe cible, la source d'un réplica. La classe la plus forte ; AWS modélise la relation pour vous.
- Un chemin que quelque chose permet — une règle de groupe de sécurité, une politique de bucket. Cela établit qu'un appel peut se produire, pas qu'il se produit. Notez lorsqu'une règle est délimitée par CIDR plutôt que par groupe de sécurité : elle autorise toute une plage, pas la seule charge de travail depuis laquelle vous avez tracé la flèche.
- Une autorisation qu'une identité détient — une déclaration de politique IAM. Même prudence, plus l'autorisation n'est pas la permission effective tant que les SCP, les limites d'autorisation et les politiques de ressources ne sont pas évaluées.
- Inférence à partir du nom ou des balises — tracez en pointillés, étiquetez avec l'incertitude, ou laissez de côté. Jamais en trait plein.
L'absence est aussi une constatation qui mérite d'être dessinée. Lorsqu'un rôle qui « de toute évidence » parle à une file d'attente s'avère ne détenir aucune action sqs:* du tout, un nœud le disant est plus utile qu'une flèche manquante, car cela écarte l'hypothèse erronée au lieu de la laisser