Draw a Kubernetes request path with Mermaid

Create a readable Kubernetes architecture diagram showing entry traffic, Services, workloads, and a worker queue without turning it into a resource inventory.

Updated November 19, 2026 · 2 min read

A Kubernetes architecture diagram should help someone follow traffic or understand an operational boundary. Drawing every resource often hides the path the reader came to inspect.

Start with one question: how does a request reach the application, and what work happens after the response? The diagram below is a logical example, not a deployable cluster specification.

Separate the request path from background work

flowchart LR
  User[User]
  subgraph Cluster[Application cluster]
    Entry[Ingress routing]
    Service[Application Service]
    API[API workload]
    Worker[Worker workload]
  end
  Queue[Message queue]
  Database[(Application database)]
  User -->|HTTPS request| Entry
  Entry --> Service
  Service --> API
  API -->|publish job| Queue
  Queue -->|deliver job| Worker
  Worker -->|write result| Database

The Service represents a stable application-facing endpoint for the workload in this simplified view. It is not drawn as another application process. The queue and database sit outside the cluster boundary here because this hypothetical deployment uses external services. Move them if the actual deployment differs.

Make the boundary honest

A subgraph is a visual grouping, not a NetworkPolicy, namespace, or security guarantee. Label it according to what it represents. If you show a namespace, say so. If you show a cluster, avoid treating the outline as proof that traffic is isolated.

The entry route also needs a real implementation. An Ingress resource requires an implementation to fulfill it; the diagram's generic ingress box does not choose or configure that implementation. Check the actual environment against the Kubernetes Ingress documentation.

Decide which operational detail belongs here

For an onboarding view, workload names and the request path may be enough. For a resilience review, add replica assumptions, failure handling, and the database dependency. For a networking review, distinguish internal and external entry points and reference the actual policy configuration.

Do not mix these audiences without a clear legend. One arrow cannot mean request routing, deployment ownership, and credential access at the same time.

Add icons after the flow is clear

Flowgraph Studio includes the official Kubernetes icons alongside AWS, Azure, Google Cloud, and general-purpose sets. The Rich node builder in the editor searches them by name and writes the @icon: line for you, so you never guess an ID. To start from a fuller example, the Templates page has a "Kubernetes platform with GitOps" diagram to cut down to your own request path. Keep labels readable even when icons are removed; a product symbol alone rarely explains the workload's role.

Arrange the main request path in one direction and place asynchronous work on a second track. If edges cross excessively, split the diagram into request and processing views rather than forcing every detail into a single canvas.

Open Flowgraph Studio with the example and adapt it to one actual service. Use the flowchart cheat sheet for subgraphs and labels. Before sharing, ask a colleague to narrate the path; their description is a practical check of what the diagram communicates.

More guides