How to Draw a Kubernetes Architecture Diagram That Holds Up

How to draw a Kubernetes architecture diagram, the short version: draw the cluster in layers (cloud and zones, node pools, namespaces, workloads, Services and entry points, data), then only draw an arrow when a label selector, a network policy or real app config proves it exists. Namespaces are zones, not walls. Network policies are the walls, and you should draw them as such.

Here's the uncomfortable truth about most Kubernetes diagrams: they're a slide with a big blue box labeled "K8s", six hexagons inside it, and arrows that someone drew from memory in 2023.

Meanwhile the real cluster has 40 namespaces, two node pools nobody remembers creating, and a Service whose selector has matched zero pods since the last rename.

Below: the layers to draw, a worked example, the selector trap that breaks most diagrams, and a review checklist.

What a Kubernetes architecture diagram should include

A useful diagram answers three questions fast: what runs where, what is exposed, and what can talk to what. Everything on the page should serve one of those.

Draw in layers, from the outside in:

Two rules keep this readable. First, don't draw individual pods; draw the workload that owns them and note the replica count. Second, if a namespace doesn't matter to the question being reviewed, collapse it to a single labeled box.

If you want the conceptual background on how clusters get split up, the cluster topology explainer covers the trade-offs.

→ Turn your manifests into a first-pass topology with the free Kubernetes YAML Visualizer

Kubernetes cluster architecture diagram: the control plane question

How much control plane belongs on a Kubernetes cluster architecture diagram depends on who operates it.

The Amazon EKS Kubernetes concepts page lays out the standard components:

• kube-apiserver exposes the Kubernetes API, so requests can come from inside and outside the cluster.
• etcd keeps track of the cluster's current state.
• kube-scheduler chooses which node a Pod runs on.
• kube-controller-manager watches cluster state and makes changes to restore the expected state.
• cloud-controller-manager handles interactions with the cloud provider, such as routes and load balancers.
• On every node: the kubelet, the container runtime (containerd by default) and kube-proxy.

The same page states that Amazon EKS "manages the security and availability of the AWS-hosted Kubernetes control plane." So on EKS, and on other managed services, the control plane is one box at the edge of the cluster with an arrow to your nodes. Drawing etcd on an EKS diagram is cosplay. It looks thorough and tells the reviewer nothing they can act on.

Self-managed cluster? Different story. Your team runs etcd, backs it up and upgrades it, so draw the control plane nodes, their zones and the etcd topology. That's where the outage risk lives.

→ Size the node pools you're about to draw with the Kubernetes Capacity Calculator

How to draw a Kubernetes architecture diagram in 6 steps

This is the workflow that produces a diagram you can defend in review. It pulls from the cluster and the manifests, not from memory.

1. Pin the scope. One cluster, one environment, one question. "How does checkout traffic reach the database in prod?" is a diagram. "Everything" is a poster.

2. Map zones and node pools.

kubectl get nodes -L topology.kubernetes.io/zone

The extra column shows which zone each node sits in. Group nodes into their pools and draw each pool once, spanning the zones it covers.

3. Inventory the workloads.

kubectl get namespaces
kubectl get deployments,statefulsets,daemonsets -A

StatefulSets deserve a different shape. The EKS docs describe them as the workload type for Pods that need to be unique, such as database Pods, and they carry storage that a reviewer needs to see.

4. Draw the entry points.

kubectl get services,ingresses -A

Every LoadBalancer Service and every Ingress host is a door to the outside. Put those doors on the cluster edge, never buried in the middle.

5. Draw only the arrows you can prove. An arrow from workload A to Service B needs evidence: an env var, a config file, a client library call. Then confirm Service B actually selects pods (more on that trap below).

6. Overlay the policy.

kubectl get networkpolicies -A

No results? Then your diagram needs a loud note: no network policies, so nothing restricts pod-to-pod traffic.

Using Helm? Render what you actually deploy before you diagram it, so you're reading real objects instead of templates:

helm template shop ./charts/shop --namespace shop > rendered.yaml

→ Paste rendered.yaml into the Kubernetes YAML Visualizer and skip the manual tracing

Kubernetes architecture diagram example: a small shop

A shop namespace runs three workloads: web, checkout and a postgres StatefulSet. Here's the slice of YAML that matters for checkout:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: checkout
  namespace: shop
spec:
  replicas: 3
  selector:
    matchLabels:
      app: checkout
  template:
    metadata:
      labels:
        app: checkout
    spec:
      containers:
        - name: checkout
          image: registry.example.com/shop/checkout:1.4.2
          ports:
            - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: checkout
  namespace: shop
spec:
  selector:
    app: checkout
  ports:
    - port: 80
      targetPort: 8080
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: checkout-allow-web
  namespace: shop
spec:
  podSelector:
    matchLabels:
      app: checkout
  policyTypes:
    - Ingress
  ingress:
    - from:
        - podSelector:
            matchLabels:
              app: web
      ports:
        - protocol: TCP
          port: 8080

From that YAML plus the app config, the diagram's edges look like this:

Notice what the table does: every line has a source of truth. That's what survives the "wait, is that still true?" question in review.

Also notice what's missing. There's no policy around postgres yet, so any pod in the cluster that can resolve it can try to connect. That's a finding, and the diagram should show it, not hide it.

→ Generate this kind of topology from a plain-English prompt with Architect AI

The selector trap: why Kubernetes diagrams lie

Kubernetes doesn't wire Services to workloads by name. It wires them by labels. A Service's selector matches pod labels, and the matching pods become its endpoints.

That means a one-character typo breaks the link while everything still looks fine on paper:

spec:
  selector:
    app: check-out   # pods are labeled app: checkout

The Service exists. The Deployment exists. Your hand-drawn diagram shows an arrow between them. And the Service routes to nothing.

Check it before you draw it:

kubectl get pods -n shop --show-labels
kubectl get endpointslices -n shop -l kubernetes.io/service-name=checkout

If the EndpointSlice lists no pod addresses, the arrow you were about to draw doesn't exist. This is exactly why diagrams generated from manifests beat diagrams drawn from memory: the selector match is either there or it isn't, no vibes involved.

→ See how your selectors line up with the free Kubernetes YAML Visualizer

Kubernetes network policy diagram: draw walls, not vibes

The single most common mistake on a Kubernetes architecture diagram is drawing namespaces as security boundaries. They aren't, at least not on their own.

Google's GKE network policy documentation is blunt about it: "By default, all Pods within a cluster can communicate with each other freely." It also notes that network policy "requires a network plugin to implement enforcement" and "If no network plugin is configured, network policies aren't enforced."

So your diagram needs two separate visual languages:

• Namespace = dashed zone. It groups things. It doesn't block traffic.
• Network policy = solid boundary. Draw it only where a policy selects the pods and your cluster's network plugin enforces it.

A quick way to show this on one page:

If you want the deeper "why", the network policy explainer and the workload isolation explainer walk through how teams layer these controls.

→ Threat-model those trust zones with Threat Analyzer

Kubernetes architecture diagram generator options compared

You have four realistic ways to produce the diagram. Each fits a different job, so here's the honest version:

The pattern most platform teams land on: generate the current state from manifests, design the target state from intent, and keep both next to each other in the review. Architecto's Kubernetes and cloud-native guides collect the templates and explainers that sit around that workflow.

If you're coming from Docker Compose, the same evidence-first method applies; our Docker Compose network diagram guide shows how networks and ports translate before you move to Kubernetes. And if your cluster lives on AWS, pair this with the AWS architecture diagram guide so the VPC, subnets and load balancers around the cluster are drawn just as carefully.

→ Design your target cluster architecture with Architect AI

Kubernetes diagram review checklist

Run this before the diagram goes into a design doc or an architecture review:

• Scope is stated: cluster, environment and the question the diagram answers
• Node pools are drawn once, spanning the zones they actually cover
• Control plane is one box on managed clusters; components and etcd on self-managed
• Every namespace in scope is a dashed zone, not a security wall
• Workloads are drawn as Deployments, StatefulSets or DaemonSets, with replica counts
• Every Service arrow is backed by a selector that has endpoints
• Every entry point (Ingress host, LoadBalancer Service) sits on the cluster edge
• Stateful workloads show their storage
• Network policies are drawn as solid boundaries, and only where they're enforced
• Namespaces with no policy are flagged
• External dependencies (managed databases, queues, third-party APIs) are outside the cluster box
• The diagram has a date and a source (manifest commit, cluster name or IaC path)

→ Turn this checklist into a reusable review template with the Architecture Review Checklist Builder

Key takeaways

• Draw in layers: cloud and zones, node pools, namespaces, workloads, entry points, data, policy.
• On managed Kubernetes, the control plane is one box. Spend the detail on things your team operates.
• Arrows need evidence: a selector with endpoints, a policy rule or real app config.
• Namespaces group; network policies restrict, and only when the network plugin enforces them.
• Generate current state from manifests, design target state from intent, and review both side by side.

→ Start your Kubernetes diagram from real manifests, free

FAQ

What should a Kubernetes architecture diagram include?

At minimum: the cluster boundary and where it runs, node pools and availability zones, namespaces as zones, the workloads in each namespace, the Services and Ingress or load balancers that expose them, the stateful dependencies inside and outside the cluster, and the network policies that restrict traffic. Every arrow should trace back to a selector, a policy or real application config.

Should I draw the Kubernetes control plane on my architecture diagram?

On a managed service such as Amazon EKS, draw it as one box at the cluster boundary. AWS documents that EKS manages the security and availability of the AWS-hosted control plane, so its internals rarely matter to an application review. On self-managed clusters, draw the control plane components and etcd, because your team operates them.

How do I generate a Kubernetes architecture diagram from YAML?

Collect the manifests you actually deploy (render Helm charts with helm template first), then parse them into workloads, Services and Ingress objects and connect them through label selectors. Architecto's free Kubernetes YAML Visualizer does this in the browser and returns a Mermaid topology plus an object inventory by kind, name and namespace.

Can pods in different namespaces talk to each other by default?

Yes. Google's GKE documentation states that by default all Pods within a cluster can communicate with each other freely. Namespaces organize objects; network policies restrict traffic, and only when a network plugin enforces them.

→ Compare Architecto with Eraser for technical diagrams

Ship a diagram your platform team actually trusts

The diagram nobody updates is worse than no diagram, because people still believe it. Build yours from evidence: manifests for what exists, policies for what's blocked, and intent for where you're going next.

Start with your rendered YAML today, then move the target-state design into Architecto when you're ready to review cost, threats and documentation in one place.

→ Start free and build your Kubernetes architecture in Architecto

→ See how Architect AI turns a prompt into a reviewable topology