Kubernetes diagrams

Ingress, workloads, storage and RBAC: the four questions people actually ask.

Kubernetes resources drawn with the standard icon set. These are worth drawing because the interesting parts of a cluster are relationships that no dashboard shows on one screen: which service selects which pods, which role binding grants what, and which volume survives a restart.

Most Kubernetes confusion is not about YAML. It is about not being able to see the graph.

When to use these

Explaining how traffic reaches a pod, which is the single most asked question about any cluster.
Reviewing RBAC, where the damage is done by a binding nobody drew.
Documenting what is stateful, before someone assumes nothing is.

When not to

Cluster capacity or cost. That is a chart, not a diagram.
The application architecture itself. Kubernetes is where it runs, not what it is.

Common mistakes

Drawing pods as the unit is the usual error. Pods are cattle and the diagram dates the moment one is rescheduled. Draw Deployments, Services and the things that persist.

The 5 templates

Cluster Overview.puml

The whole cluster at a glance. The one to draw first.

Show the source

@startuml
!define KubernetesPuml https://raw.githubusercontent.com/dcasati/kubernetes-PlantUML/master/dist
!include KubernetesPuml/kubernetes_Common.puml
!include KubernetesPuml/kubernetes_Simplified.puml
!include KubernetesPuml/OSS/KubernetesMaster.puml
!include KubernetesPuml/OSS/KubernetesNode.puml
!include KubernetesPuml/OSS/KubernetesPod.puml
!include KubernetesPuml/OSS/KubernetesSvc.puml
!include KubernetesPuml/OSS/KubernetesEtcd.puml

title Kubernetes — Cluster overview

KubernetesMaster(master, "control-plane", "")
KubernetesEtcd(etcd, "etcd", "cluster store")
KubernetesNode(node1, "node-1", "")
KubernetesNode(node2, "node-2", "")
KubernetesPod(pod1, "api", "")
KubernetesPod(pod2, "worker", "")
KubernetesSvc(svc, "api-svc", "ClusterIP")

master --> etcd
master --> node1
master --> node2
node1 --> pod1

The rest of this template, and how to use it

Ingress to Pods.puml

Ingress to service to pods. How traffic actually gets in.

Show the source

@startuml
!define KubernetesPuml https://raw.githubusercontent.com/dcasati/kubernetes-PlantUML/master/dist
!include KubernetesPuml/kubernetes_Common.puml
!include KubernetesPuml/kubernetes_Simplified.puml
!include KubernetesPuml/OSS/KubernetesIng.puml
!include KubernetesPuml/OSS/KubernetesSvc.puml
!include KubernetesPuml/OSS/KubernetesPod.puml
!include KubernetesPuml/OSS/KubernetesDeploy.puml

title Kubernetes — Ingress to Pods

left to right direction

KubernetesIng(ing, "web-ingress", "nginx")
KubernetesSvc(svc, "web-svc", "ClusterIP")
KubernetesDeploy(deploy, "web", "3 replicas")
KubernetesPod(pod1, "web-a", "")
KubernetesPod(pod2, "web-b", "")

ing --> svc
svc --> pod1
svc --> pod2
deploy ..> pod1
deploy ..> pod2

The rest of this template, and how to use it

Workload and Configuration.puml

Deployments with their config and secrets attached.

Workload and Configuration: rendered example

Show the source

@startuml
!define KubernetesPuml https://raw.githubusercontent.com/dcasati/kubernetes-PlantUML/master/dist
!include KubernetesPuml/kubernetes_Common.puml
!include KubernetesPuml/kubernetes_Simplified.puml
!include KubernetesPuml/OSS/KubernetesDeploy.puml
!include KubernetesPuml/OSS/KubernetesRs.puml
!include KubernetesPuml/OSS/KubernetesPod.puml
!include KubernetesPuml/OSS/KubernetesHpa.puml
!include KubernetesPuml/OSS/KubernetesCm.puml
!include KubernetesPuml/OSS/KubernetesSecret.puml

title Kubernetes — Workload and configuration

KubernetesDeploy(deploy, "checkout", "3 replicas")
KubernetesRs(rs, "checkout-7f4b", "")
KubernetesPod(pod1, "checkout-a", "")
KubernetesPod(pod2, "checkout-b", "")
KubernetesHpa(hpa, "checkout-hpa", "2-10 pods")
KubernetesCm(cm, "checkout-config", "")
KubernetesSecret(secret, "checkout-creds", "")

deploy --> rs
rs --> pod1
rs --> pod2

The rest of this template, and how to use it

Stateful Storage.puml

Persistent volumes and claims. What survives a restart, and what does not.

Show the source

@startuml
!define KubernetesPuml https://raw.githubusercontent.com/dcasati/kubernetes-PlantUML/master/dist
!include KubernetesPuml/kubernetes_Common.puml
!include KubernetesPuml/kubernetes_Simplified.puml
!include KubernetesPuml/OSS/KubernetesSts.puml
!include KubernetesPuml/OSS/KubernetesPod.puml
!include KubernetesPuml/OSS/KubernetesPvc.puml
!include KubernetesPuml/OSS/KubernetesPv.puml
!include KubernetesPuml/OSS/KubernetesSc.puml

title Kubernetes — Stateful storage

KubernetesSts(sts, "postgres", "2 replicas")
KubernetesPod(pod1, "postgres-0", "")
KubernetesPod(pod2, "postgres-1", "")
KubernetesPvc(pvc1, "data-postgres-0", "20Gi")
KubernetesPvc(pvc2, "data-postgres-1", "20Gi")
KubernetesPv(pv1, "pv-a", "")
KubernetesPv(pv2, "pv-b", "")
KubernetesSc(sc, "fast-ssd", "dynamic")

sts --> pod1
sts --> pod2
pod1 --> pvc1

The rest of this template, and how to use it

RBAC.puml

Roles and bindings. The diagram that finds the over-permissive service account.

Show the source

@startuml
!define KubernetesPuml https://raw.githubusercontent.com/dcasati/kubernetes-PlantUML/master/dist
!include KubernetesPuml/kubernetes_Common.puml
!include KubernetesPuml/kubernetes_Simplified.puml
!include KubernetesPuml/OSS/KubernetesUser.puml
!include KubernetesPuml/OSS/KubernetesGroup.puml
!include KubernetesPuml/OSS/KubernetesSa.puml
!include KubernetesPuml/OSS/KubernetesRole.puml
!include KubernetesPuml/OSS/KubernetesRb.puml
!include KubernetesPuml/OSS/KubernetesNs.puml

title Kubernetes — RBAC

KubernetesUser(user, "alice", "human")
KubernetesGroup(group, "platform", "")
KubernetesSa(sa, "deploy-bot", "in-cluster")
KubernetesRole(role, "deployer", "namespaced")
KubernetesRb(rb, "deployer-binding", "")
KubernetesNs(ns, "production", "")

user --> group
group --> rb
sa --> rb
rb --> role

The rest of this template, and how to use it

Render these offline

Every template here ships in Gnomon and renders on your machine, with no account and nothing sent to a server. The browser editor is free and needs no install.

Get Gnomon Open the browser editor