AWS-Architekturdiagramme im AWS-Stil
Überblick
Erstellen Sie Diagramme, die den Konventionen von AWS-Referenzarchitekturdiagrammen folgen: genaue Servicenamen, beschriftete Konto-/Region/VPC-Grenzen, kurze Flussbeschriftungen und eine übersichtliche Leinwand. „AWS-Stil" beschreibt diese Konventionen; es erfordert nicht zwingend offizielle AWS-Symbole oder Graphviz.
Mermaid und Graphviz DOT sind gleichwertige Autorenformate. Mermaid eignet sich oft für Inline-, themenbewusste, textbasierte überprüfbare Dokumentation; DOT eignet sich oft für exakte lokale AWS-Symbol-Assets, kontrollierte Komposition und präsentationsreife SVG/PNG. Verwenden Sie eines, wenn es den vollständigen Liefervertrag erfüllt, und beide, wenn unterschiedliche Zielgruppen oder Artefakte den zusätzlichen Wartungsaufwand rechtfertigen.
Wann verwenden
Verwenden Sie diese Fähigkeit für evidenzbasierte AWS-Architektur-, Topologie-, Systemkontext- oder Datenflussdiagramme. Verwenden Sie sie nicht für ein nicht-AWS-Visual oder wenn eine Tabelle allein die angeforderten Fakten klarer vermittelt.
Häufige Rechtfertigungen
- „AWS-Stil bedeutet DOT" ignoriert Mermaid-Renderer, die den tatsächlichen Vertrag erfüllen.
- „Beide Formate sind sicherer" erzeugt Synchronisationskosten ohne zwei benannte Verbraucher.
- „Der Dienst verbindet sich wahrscheinlich hier" ist kein Beweis für eine Kante.
Warnsignale
Stoppen Sie und klären Sie nicht unterstützte Ressourcen oder Beziehungen, einen mehrdeutigen Ziel-Renderer, fehlende Icon-Rechte oder -Assets, widersprüchliche Quellnachweise oder eine angeforderte Region außerhalb des autorisierten Bereichs, bevor Sie zeichnen oder Live-Infrastruktur abfragen.
Die Regel, die über der Ästhetik steht
Zeichnen Sie nur, was die Quelle belegt. Jeder Knoten, jede Kante, jede Grenze, jede Region und jedes Protokoll muss auf etwas Reales zurückverfolgbar sein – Terraform, CloudFormation, CDK, bereitgestellte Konfiguration oder eine schriftliche Aussage des Besitzers. Ein Diagramm ist ein Beweisartefakt, das zufällig visuell ist.
Fügen Sie niemals einen Dienst, eine Verbindung, eine Availability Zone, ein VPC oder eine Region hinzu, weil das Bild ohne sie unausgeglichen aussieht. Wenn die Quelle keine Grenze festlegt, lassen Sie sie weg; ein ehrliches spärliches Diagramm schlägt ein dekoratives vollständiges. Wenn etwas bereitgestellt, aber deaktiviert ist, vermerken Sie dies am Knoten (WEB_PUSH_ENABLED=false, „Bereitgestellt, veröffentlichungsdeaktiviert"), anstatt es so zu zeichnen, als wäre es live, und markieren Sie, was einem anderen Team gehört, damit ein Leser nicht denkt, Sie kontrollieren es.
Geben Sie die Herkunft im Diagramm selbst an – einen Untertitel, der die Quelle nennt, z. B. „zurückverfolgt zu <iac-dir>/*.tf bei <revision>" oder „Live-Read-Only-Bestand, <date>" – und wiederholen Sie sie in einem Header-Kommentar im DOT-Quellcode.
Benennen Sie die Ressource, nicht nur den Dienst
Ein Dienstsymbol allein identifiziert nichts. Ein magentafarbener DynamoDB-Glyphe mit der Bezeichnung „Operations" könnte eine Tabelle, ein Stream oder ein Index sein, und ein Leser hat keine Möglichkeit, ihn in der Konsole zu finden. Jeder Knoten gibt drei Fakten an:
- Wie es in AWS heißt. Der echte bereitgestellte Name –
acme-orders-events, kein freundlicher Alias wie „Aufträge". Schreiben Sie eine Konto-ID als<account>anstelle der Ziffern; setzen Sie niemals ein Geheimnis, Token oder einen Endpunkt in ein Diagramm. - Welche Art von Ressource es ist. Ausgeschrieben, in Grau, unter dem Namen: „DynamoDB-Tabelle", „S3-Bucket", „Lambda-Funktion", „API Gateway HTTP API", „WAFv2 Web ACL", „SES v2 E-Mail-Identität".
- Wofür es ist. Eine Zeile, und nur dort, wo ein Leser es nicht ableiten könnte.
Verwenden Sie für die Graphviz-Ausgabe ein Ressourcensymbol (Res_Amazon-DynamoDB_Table, Res_Amazon-Simple-Storage-Service_Bucket, Res_AWS-Lambda_Lambda-Function), wo AWS eines veröffentlicht, und ein Dienstsymbol (Arch_) für alles andere. Das Symbol verstärkt die Identität; es darf niemals das Einzige sein, das sie trägt, denn ein Symbol ist in Graustufen, in Thumbnail-Größe oder von einem Screenreader nicht lesbar.
Wählen Sie das Format basierend auf den Anforderungen
Es gibt keinen globalen Gewinner und kein Standardformat. Ehren Sie ein explizit angefordertes Quellformat, es sei denn, es widerspricht einem anderen Akzeptanzkriterium. Vergleichen Sie andernfalls die tatsächlichen Lieferanforderungen:
| Anforderung | Mermaid neigt dazu, besser geeignet | Graphviz DOT neigt dazu, besser geeignet |
|---|---|---|
| Repository-Review | Inline-Markdown-Rendering, kompakte Text-Diffs | Überprüfbare Textquelle plus separat gerenderte Artefakte |
| Diagrammtyp | Sequenz-, Fluss-, Zustands-, Abhängigkeits- und einfache Architekturansichten | Dichte Topologie, verschachtelte Grenzen und Graphen, die gezielten Kantenverlauf benötigen |
| AWS-Visuals | AWS-Stil-Namen, -Grenzen, -Farben oder vom Renderer bereitgestellte Symbolpakete | Exakte, repo-lokale, von AWS veröffentlichte Symbol-Assets |
| Layout | Vom Renderer verwaltetes responsives Layout und Themaanpassung | Präzise Ränge, Ports, Cluster, Abstände und feste Komposition |
| Lieferung | Dokumentation, die dort rendern sollte, wo sie geschrieben wird | Kontrollierte SVG/PNG für Präsentationen, Dokumente und Präsentationsflächen |
| Werkzeuge | Der Ziel-Renderer unterstützt bereits die erforderliche Mermaid-Syntax und -Version | Graphviz und die erforderlichen lokalen Assets sind in der Build- oder Authoring-Umgebung verfügbar |
Wenn der angeforderte Inhalt tatsächlich tabellarisch ist, verwenden Sie eine Markdown-Tabelle, anstatt ihn in ein Bild zu verwandeln. Für einen geordneten Teilnehmeraustausch ist Mermaid sequenceDiagram normalerweise die natürliche Wahl; dies ist ein Vorteil des Diagrammtyps, keine allgemeine Präferenz für Mermaid.
Mermaid unterstützt Architekturdiagramme und konfigurierbare Symbolpakete, aber ein gehosteter Renderer kann nicht angenommen werden, dass er repo-lokale AWS-Assets, benutzerdefinierte Paketregistrierung oder dieselbe Mermaid-Version wie ein kontrollierter lokaler Renderer bereitstellt. Graphviz kann lokale Bild-Assets direkt laden, daher ist es die zuverlässige Wahl, wenn exakte Symbol-Assets und feste exportierte Komposition Akzeptanzkriterien sind, nicht nur, weil die Anfrage „AWS-Stil" sagt.
Zählen Sie die Kompromisse auf beiden Seiten. Mermaid kann zwischen Renderer-Versionen, verfügbaren Symbolpaketen und Host-Designs variieren. DOT fügt einen Rendering-Schritt und generierte Artefakte hinzu, die mit der bearbeitbaren Quelle synchron bleiben müssen. Wählen Sie das Format, dessen Kosten zum Repository und Ziel passen, anstatt die Stärken beider Tools als universell zu behandeln.
Wenn Renderer-Unterstützung, Symboltreue, feste Komposition oder erwartete Ausgabedateien das Ergebnis wesentlich verändern würden und die Anfrage mehrdeutig ist, klären Sie den Liefervertrag. Andernfalls wählen Sie das Format, das die bekannten Anforderungen mit dem geringsten projektspezifischen Aufwand erfüllt.
Wenn Mermaid ausgewählt wird, behalten Sie die oben genannten Regeln für Nachweise, Herkunft, Ressourcennamen und Barrierefreiheit bei, validieren Sie die Quelle im Ziel-Renderer und stoppen Sie vor dem unten beschriebenen Graphviz-spezifischen Workflow.
Wenn beide Formate gerechtfertigt sind
Produzieren Sie Mermaid und DOT, wenn sie unterschiedliche reale Anforderungen erfüllen, wie z. B. Inline-Repository-Review plus exakte AWS-Symbol-Präsentationsausgabe. Doppelte Lieferung ist nicht automatisch besser: Sie ist nur gerechtfertigt, wenn beide Artefakte einen benannten Verbraucher oder ein benanntes Akzeptanzkriterium haben.
Keine Quelle ist standardmäßig kanonisch. Leiten Sie beide aus demselben verifizierten Ressourcen- und Beziehungsinventar ab, tragen Sie dieselbe Herkunft und überprüfen Sie, ob Knoten, Kanten, Grenzen, Regionen, Besitzverhältnisse und Unsicherheiten übereinstimmen. Ein Format kann präsentationsspezifische Struktur hinzufügen, ohne die Architektur zu ändern, die es behauptet. Nennen Sie ein Format nur dann autoritativ, wenn der Benutzer oder die Repository-Richtlinie diese Rolle explizit zuweist.
Für eine ungewöhnlich dichte vollständige Systemkarte, die exakte AWS-Symbole, feste Komposition oder portlevel-Konnektorplatzierung benötigt, können DOT plus sein SVG und PNG als Präsentations- und AWS-Symbol-Artefakt dienen. Ein Mermaid-Rendering kann als wartbarer, inline-überprüfbarer Begleiter dienen, wenn dies auch erforderlich ist. Für einen fokussierten Fluss ohne diese DOT-spezifischen Anforderungen kann Mermaid allein den Vertrag erfüllen. Dies sind anforderungsgesteuerte Entscheidungen, kein Grund, beide Formate für jedes Diagramm zu produzieren.
Mermaid-Workflow
1. Wählen Sie den Mermaid-Diagrammtyp
Verwenden Sie architecture-beta oder ein Flussdiagramm für Architektur und Topologie, ein sequenceDiagram für geordnete Austausche und ein Zustandsdiagramm nur für tatsächliche Zustandsübergänge. Bestätigen Sie, dass der Ziel-Renderer die ausgewählte Syntax und eventuelle Symbolpakete unterstützt; gehen Sie nicht davon aus, dass GitHub, eine Dokumentationsseite und eine lokale Mermaid-CLI dieselbe Version oder Konfiguration ausführen. Wenn Sie Iconify-Symbole verwenden, behalten Sie den vollständigen AWS-Ressourcennamen und -Typ im Text; ein Symbol darf niemals der einzige Ressourcenidentifikator sein.
2. Codieren Sie das verifizierte Inventar
Stellen Sie AWS-Konto, Region, VPC, Availability Zone, Subnetz und Besitzgrenzen nur dar, wenn die Nachweise sie belegen. Verwenden Sie vollständige Ressourcennamen und -typen, kurze beschriftete Kanten und sichtbare Anmerkungen für erlaubte oder abgeleitete Beziehungen. Bewahren Sie die Herkunft in nahem Markdown und, wenn die Syntax es erlaubt, in einem Quellkommentar auf.
3. Rendern und inspizieren Sie in der Zielumgebung
Verwenden Sie den festgelegten Mermaid-Befehl des Repositorys oder den Dokumentationsbuild. Validieren Sie den genauen Fenced-Block oder die .mmd-Quelle, die ausgeliefert werden soll, und inspizieren Sie dann das gerenderte Ergebnis in seiner vorgesehenen Breite und seinem Design. Überprüfen Sie abgeschnittene Beschriftungen, überlappende Kanten, nicht unterstützte Symbole oder Syntax, unzugänglichen Kontrast und semantische Abweichungen vom verifizierten Inventar. Korrigieren Sie die bearbeitbare Quelle und rendern Sie erneut, bis sie lesbar ist.
Registrieren Sie nicht eingebaute Symbolpakete explizit. Für die Mermaid-CLI kann ein reproduzierbarer AWS-Symbol-Render wie folgt aussehen:
mmdc --iconPacks '@iconify-json/logos' \
-i system-context-aws.mmd -o system-context-aws.svg -b white
Behandeln Sie ein ? als Fehlerfall, nicht als kosmetische Beeinträchtigung. Die Unterstützung von Symbolpaketen kann je nach Mermaid-Version und Layout-Renderer variieren; überprüfen Sie die tatsächliche Ausgabe visuell und strukturell. Wenn ein unterstützter Renderer registrierte Symbole verliert, verwenden Sie einen anderen unterstützten Renderer, der sie beibehält, und dokumentieren Sie den Layout-Kompromiss. Beanspruchen Sie keine Inline-Portabilität, es sei denn, der Ziel-Host registriert ebenfalls das erforderliche Paket.
4. Liefern Sie die erforderlichen Artefakte
Behalten Sie Mermaid inline, wenn dies der Repository-Vertrag ist. Wenn eigenständige SVG- oder PNG-Ausgaben erforderlich sind, rendern Sie diese deterministisch mit der festgelegten Mermaid-Version des Repositorys und dokumentieren Sie den Reproduktionsbefehl.
Graphviz-Workflow
1. Ermitteln Sie die Architektur aus der Quelle
Lesen Sie die IaC und inventarisieren Sie, was tatsächlich existiert, bevor Sie etwas zeichnen. Finden Sie das Verzeichnis, in dem dieses Projekt es aufbewahrt – infra/, terraform/, deploy/, eine CDK-App – anstatt ein Layout anzunehmen:
iac_dir=infra # was auch immer dieses Repository tatsächlich verwendet
grep -hoE '^resource "aws_[a-z0-9_]+"' "$iac_dir"/*.tf | sort | uniq -c | sort -rn
Ziehen Sie dann die Details, die Kanten real machen und die Namen, die auf die Knoten kommen: Funktionsnamen, Tabellennamen, Bucket-Namen, Ereignisregeln und deren Zeitpläne, S3-Benachrichtigungen, Autorisierer und alle Cross-Account- oder Cross-Stack-Grants. Lösen Sie Namen über ihre Variablen und Locals auf den tatsächlich bereitgestellten Wert auf. Notieren Sie die Region aus der Variable, die sie setzt, nicht aus Annahme.
1b. Wenn es kein IaC gibt oder das IaC nur einen Teil des Bestands abdeckt
Manchmal ist das zu diagrammierende Objekt ein laufendes Konto, für das niemand Terraform hat, oder das Terraform deckt nur einen Bruchteil dessen ab, was bereitgestellt ist. Dann ist die Quelle das Live-Konto, schreibgeschützt, und das Diagramm muss explizit sein, dass es das ist, was es ist.
Beginnen Sie mit einem Tag-Prädikat anstatt einem Service-für-Service-Durchlauf, weil es die einzige Möglichkeit ist, zu begrenzen, „was zu diesem System gehört":
aws resourcegroupstaggingapi get-resources --region <region> \
--tag-filters 'Key=<key>,Values=<v1>,<v2>'
Mehrere Tag-Schlüssel benötigen jeweils eine Anfrage, die später per ARN vereinigt wird – die Übergabe von zwei Schlüsseln in einer Anfrage wendet UND an und lässt stillschweigend alles fallen, das nur eines der beiden trägt. Notieren Sie die resultierende Anzahl und das Datum; es ist ein Snapshot, kein Fakt.
Die Tagging-API gibt nicht alle Ressourcentypen zurück, und Tags sind kein Eigentumsnachweis. Die Tag-Abfrage gibt Ihnen also die Knotenmenge, und Beziehungen kommen von den APIs, die sie tatsächlich modellieren:
| Um festzustellen | Lesen Sie |
|---|---|
| Eingangsverkabelung | elbv2 describe-load-balancers, describe-target-groups |
| Welche Pfade erlaubt sind | ec2 describe-security-groups, describe-vpcs |
| Was eine Compute-Ebene aufrufen darf | iam get-instance-profile, dann get-policy-version |
| Datenebenen-Form und -Replikate | rds describe-db-instances, elasticache describe-* |
| Asynchrone Verkabelung | Warteschlangen-Redrive-Richtlinien, S3-Benachrichtigungen, Ereignisregeln |
Lösen Sie jeden CIDR, den Sie finden, in ein benanntes VPC auf, bevor Sie es zeichnen; ein ungelöstes 10.16.0.0/16 in einem Diagramm sagt einem Leser nichts.
1c. Sagen Sie, auf welcher Art von Beweisen jede Kante basiert
Dies ist am wichtigsten beim Lesen eines Live-Kontos, wo es verlockend ist, eine Linie zu zeichnen, weil zwei Ressourcen ein gemeinsames Namenspräfix haben. Trennen Sie die Klassen visuell und definieren Sie sie im Diagramm und seinem Prosa:
- Verkabelung, die AWS selbst meldet – die Ziele einer Zielgruppe, die Quelle eines Replikats. Die stärkste Klasse; AWS modelliert die Beziehung für Sie.
- Ein Pfad, den etwas erlaubt – eine Sicherheitsgruppenregel, eine Bucket-Richtlinie. Dies stellt fest, dass ein Aufruf möglicherweise stattfindet, nicht dass er es tut. Notieren Sie, wenn eine Regel CIDR-begrenzt statt Sicherheitsgruppen-begrenzt ist: Sie autorisiert einen gesamten Bereich, nicht die eine Workload, von der Sie den Pfeil gezeichnet haben.
- Eine Berechtigung, die eine Identität hält – eine IAM-Richtlinienanweisung. Gleiche Vorsicht, plus die Berechtigung ist nicht die effektive Erlaubnis, bis SCPs, Berechtigungsgrenzen und Ressourcenrichtlinien ausgewertet sind.
- Schlussfolgerung aus Benennung oder Tags – zeichnen Sie gestrichelt, beschriften Sie mit der Unsicherheit oder lassen Sie es weg. Niemals durchgezogen.
Abwesenheit ist auch ein Befund, der es wert ist, gezeichnet zu werden. Wenn sich herausstellt, dass eine Rolle, die „offensichtlich" mit einer Warteschlange spricht, überhaupt keine sqs:*-Aktion hat, ist ein Knoten, der dies sagt, nützlicher als ein fehlender Pfeil, weil er die falsche Annahme ausschließt, anstatt sie
… [für die Übersetzung abgeschnitten]