Kubernetes-Architekturdiagramm zeichnen (mit kostenloser Vorlage)

Die meisten Kubernetes-Diagramme scheitern auf eine von zwei Arten: Sie sind eine Wand aus Pod-Icons, die niemand lesen kann, oder eine Skizze mit drei Kästen, auf der "Cluster" steht und sonst kaum etwas. Ein nützliches Kubernetes-Architekturdiagramm liegt dazwischen. Es zeigt, wo Traffic hereinkommt, welche Objekte ihn weiterleiten, wo Zustand liegt und welche Grenzen zählen – in einer Detailtiefe, die zu der Person passt, die es liest.

Dieser Leitfaden zeigt dir, was hineingehört, wie du die Detailtiefe nach Zielgruppe wählst, welche Fehler Diagramme nutzlos machen und wie du eines Schritt für Schritt in Archboard baust. Die kostenlose Vorlage öffnet sich mit einem Klick als neues Diagramm in deinem eigenen Workspace.

Was ein gutes Kubernetes-Architekturdiagramm zeigt

Die Kubernetes-Doku beschreibt die Cluster-Komponenten: Control Plane, kubelet, kube-proxy und so weiter. Das ist die Plattformsicht. Die meisten Teams brauchen die Workload-Sicht: wie deine Anwendung auf dem Cluster läuft. Fünf Dinge tragen den Großteil des Nutzens.

1. Cluster- und Namespace-Grenzen

Zeichne den Cluster als äußere Grenze und Namespaces als Rahmen darin. Auf Namespace-Ebene greifen RBAC, Resource Quotas und die meisten NetworkPolicies – deshalb fragen Leute zuerst nach diesen Grenzen ("Läuft payments in einem eigenen Namespace?"). Wenn du mehrere Cluster betreibst (Prod und Staging oder einen pro Region), gib jedem eine eigene Grenze und beschrifte sie mit Name und Umgebung.

2. Nord-Süd-Traffic

Zeige den Request-Pfad von außerhalb des Clusters nach innen:

Client → Ingress → Service → Deployment → Pods

Mach die Richtung mit Pfeilen eindeutig. Notiere die Host- und Pfadregeln des Ingress sowie Typ und Port des Service. Dieser eine Pfad beantwortet bei einem Incident die meisten Fragen der Art "Wohin geht dieser Request?".

Ost-West-Traffic (Service zu Service innerhalb des Clusters) ist auch wichtig, aber zeichne ihn selektiv: die Aufrufe, die Namespaces überqueren oder auf dem kritischen Pfad liegen.

3. Konfiguration und Storage

Hänge ConfigMaps, Secrets und PersistentVolumeClaims an die Workloads, die sie nutzen. Ein Deployment mit einem Secret und einem PVC sagt dem Leser zweierlei: Dieser Workload hat Zugangsdaten, und er hat Zustand, der einen Pod überlebt. Zeichne externen Zustand, etwa ein verwaltetes Postgres, außerhalb der Cluster-Grenze, damit klar ist, was dem Cluster gehört und was nicht.

4. Skalierung

Setz einen HorizontalPodAutoscaler neben das Deployment, auf das er zielt, mit Min/Max-Replicas und der Metrik im Namen oder in einer Notiz ("2–10, CPU 70 %"). Das sagt mehr als zehn gezeichnete Pods.

5. NetworkPolicy

Wenn du NetworkPolicies nutzt, zeig, welche gelten und was sie erlauben. Ein Security-Reviewer will "nur der api-Namespace erreicht Postgres" sehen, nicht erschließen.

Wie Manifeste zu Diagramm-Nodes werden

Nimm drei gewöhnliche Objekte:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: orders-api
  namespace: shop
spec:
  replicas: 3
  selector:
    matchLabels: { app: orders-api }
  template:
    metadata:
      labels: { app: orders-api }
    spec:
      containers:
        - name: api
          image: registry.example.com/orders-api:1.4.2
          ports: [{ containerPort: 8080 }]
          envFrom: [{ secretRef: { name: orders-db } }]
---
apiVersion: v1
kind: Service
metadata:
  name: orders-api
  namespace: shop
spec:
  selector: { app: orders-api }
  ports: [{ port: 80, targetPort: 8080 }]
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop
  namespace: shop
spec:
  rules:
    - host: shop.example.com
      http:
        paths:
          - path: /orders
            pathType: Prefix
            backend:
              service: { name: orders-api, port: { number: 80 } }

Im Diagramm werden daraus:

Drei Replicas werden zu einem Deployment-Node mit "×3", nicht zu drei Pod-Kästen. Die Kanten folgen den Referenzen im YAML: Ingress-Backend → Service, Service-Selector → Deployment, envFrom → Secret.

Detailtiefe nach Zielgruppe wählen

Ein Diagramm passt selten für alle. Entscheide vor dem Zeichnen, für wen es ist.

Wenn zwei Zielgruppen Unterschiedliches brauchen, zeichne zwei Ansichten statt eines Diagramms, das alles auf einmal will.

Häufige Fehler

• Jede Pod-Replica zeichnen. Replicas sind eine Zahl, keine Architektur. Ein Deployment-Node mit Replica-Anzahl, plus HPA, falls es skaliert, liest sich besser als ein Raster identischer Kästen.
• Logisch und physisch mischen. Worker Nodes, Zonen und Pod-Platzierung sind eine physische Sicht; Ingress → Service → Deployment ist eine logische. Auf einem Canvas zusammen ist keine von beiden lesbar. Brauchst du die physische Sicht, mach ein eigenes Diagramm.
• Keine Traffic-Richtung. Linien ohne Pfeile sagen nicht, wer wen aufruft. Nutze gerichtete Kanten und lass den Haupt-Request-Fluss in eine Richtung laufen, von links nach rechts oder von oben nach unten.
• Veraltete Diagramme. Ein Diagramm mit den Services vom letzten Jahr schadet mehr als gar keines. Setz einen Owner und ein "Zuletzt geprüft"-Datum auf den Canvas und aktualisiere es, wenn eine Änderung einen Kasten hinzufügt oder entfernt.
• Unerklärte Kanten. "Service → Deployment" ist offensichtlich; "orders-api → payments-api" verdient Protokoll und Port.

Schritt für Schritt in Archboard zeichnen

Das Kubernetes-Pack von Archboard hat 33 vollwertige Node-Typen mit Ports, von Namespace (als Frame gezeichnet), Node, Pod, Deployment, StatefulSet, Job und CronJob bis zu Service, Ingress, Gateway-API-Routen, ConfigMap, Secret, PersistentVolumeClaim, HPA, NetworkPolicy und RBAC. Du verbindest Ports, statt lose Linien zwischen generischen Formen zu ziehen. Du kannst mit Aus YAML importieren… von deinen Manifesten ausgehen oder jeden Node von Hand platzieren; so oder so bleibt die Entscheidung „Was ist hier wichtig?“, um die es in diesem Leitfaden geht, bei dir.

1. Beispiele studieren. Öffne das Kubernetes-Microservices-Beispiel (Ingress → Service → Deployment/Pod → PVC → Postgres) und das Ingress-Flow-Beispiel. Achte auf das Layout: Der Traffic fließt in eine Richtung, der Zustand sitzt am Ende.
2. Leg ein Diagramm an in deinem Workspace und füge einen Frame für den Cluster hinzu, benannt nach Cluster und Umgebung.
3. Füge einen Namespace hinzu für jeden relevanten Namespace, innerhalb des Cluster-Rahmens.
4. Platziere den Request-Pfad: Ingress, dann Service, dann Deployment, von links nach rechts. Verbinde Port mit Port und ergänze kurze Text-Labels für Host/Pfad und Ports.
5. Hänge Konfiguration und Zustand an: ConfigMap und Secret neben das Deployment, das sie liest, ein PVC für persistenten Speicher und einen Datenbank-Node außerhalb des Cluster-Rahmens für ein verwaltetes Postgres.
6. Ergänze Skalierung und Policies: einen HPA neben seinem Deployment mit Min/Max und Metrik sowie NetworkPolicy-Nodes an den Namespace-Grenzen, die sie schützen.
7. Gib dem Canvas Kontext: einen Markdown-Block mit Owner, Prüfdatum und Links zu Repo oder Runbook. Codeblöcke funktionieren auf dem Canvas ebenfalls, sodass der wichtigste Manifest-Ausschnitt direkt neben seinen Nodes stehen kann.
8. Teile es: Exportiere SVG oder PNG für ein Design-Dokument oder teile einen öffentlichen Link. Autosave und Revision-Snapshots erlauben dir, zurückzugehen, wenn ein Umbau schiefgeht.

Für eine Multi-Account-Ansicht mehrerer Cluster hat das Cloud-Pack einen Kubernetes-Cluster-Node.

Der Free-Plan enthält alle eingebauten Packs und erlaubt 15 Diagramm-Nodes pro Diagramm plus 150 Notizen und Texte – genug für den Request-Pfad eines Service. Für eine vollständige Karte mit vielen Services brauchst du wahrscheinlich Pro.

Die kostenlose Vorlage

Die kostenlose Vorlage ist /templates/kubernetes-architecture: Vorlage verwenden öffnet sie als neues Diagramm in deinem Workspace. Für ein umfassenderes Layout bietet /examples/kubernetes-microservices Dieses Beispiel verwenden; damit kopierst du es und kannst die Nodes nach deinen Services umbenennen. Nur für den Traffic-Pfad ist /examples/kubernetes-ingress-flow ein kleinerer Einstieg. Weitere Muster findest du auf der Kubernetes-Use-Case-Seite.

FAQ

Soll ich die Control Plane zeichnen? Nur wenn es im Diagramm um die Plattform selbst geht, etwa für ein Plattform-Team oder einen Upgrade-Plan. In Anwendungsdiagrammen ist die Control Plane Rauschen; Leser setzen sie voraus.

Pods oder Deployments? Deployments, mit Replica-Anzahl. Zeichne einzelne Pods nur, wenn ein bestimmter Pod zählt: ein Sidecar-Layout, eine Debugging-Session oder ein Lauf eines Job oder CronJob.

Wie halte ich es aktuell? Gib ihm einen Owner, schreib ein Prüfdatum auf den Canvas und überprüfe es zusammen mit den Pull Requests, die die gezeigten Services ändern. Ein JSON-Export des Diagramms kann im Repo neben den Manifesten liegen.

Kann ein Diagramm mehrere Cluster abdecken? Ja, auf höherer Ebene: eine Grenze pro Cluster, nur der Cluster-übergreifende Traffic eingezeichnet. Details pro Cluster gehören in eigene Diagramme.

Kostenlos starten — ein Seat, keine Kreditkarte