This sample shows how a small online shop runs on a Kubernetes cluster: which machines (nodes) exist, which pods land on each node, how Services and the ingress controller route traffic to them, and where configuration and storage come from. It is drawn as a UML deployment diagram adapted to Kubernetes: 3D boxes are nodes, rounded boxes inside them are the things deployed there.
1. The diagram
Entry. The client resolves shop.example.com and reaches a cloud load balancer created by a Service of type LoadBalancer.
Ingress controller. The load balancer forwards to the ingress-nginx pod, which reads the Ingress object (dashed, left) for host and path rules and terminates TLS.
Service web. Requests go to the web Service, a stable virtual IP that kube-proxy spreads across the matching pods on both workers.
Service api. Web pods call the api Service on port 8080. API pods receive settings from the ConfigMap and database credentials from the Secret, as environment variables or mounted files.
Database. API pods connect through the headless postgres Service to postgres-0, a StatefulSet pod with a stable name and its own PersistentVolumeClaim, so its data survives restarts.
The control plane (API server, etcd, scheduler, controller manager) decides placement but carries no application traffic, which is why no request arrow touches it.
2. How to read it
Read it from outside in: cluster, then nodes, then pods. Services sit between the nodes because they belong to no single machine. Any pod drawn only once (here ingress-nginx and postgres-0) is a single point of failure worth questioning.
3. Variant: strict UML notation
The same system with no Kubernetes vocabulary at all: «device» nodes, an «executionEnvironment» (the container runtime or the database server) and «artifact» elements for what is deployed. This version suits audiences outside the platform team and survives a move to another orchestrator, at the cost of hiding Services and replicas.
4. Pros, cons, and when to use
Pros
Shows physical placement, so anti-affinity and zone spreading can be checked.
Separates control plane, workloads and configuration clearly.
Makes stateful components (volumes, StatefulSets) stand out.
Matches the manifests: every box corresponds to a YAML object.
Useful for capacity planning: pods per node are visible.
Cons
Pod placement is decided by the scheduler and changes constantly; the picture is one moment.
Services, labels and selectors are hard to draw without a tangle of lines.
Says nothing about request order or failure handling.
Large clusters do not fit; draw one namespace at a time.
When to use
Onboarding engineers to a namespace or service.
Reviewing high availability, storage and secret handling before go-live.
When not to use
Documenting the cluster itself (draw the platform separately).
Anything that changes per deploy, such as pod names or exact replica counts.
5. Diagrams-as-code
A Mermaid flowchart with subgraphs for nodes is the quickest way to keep this in a repository: