# Kubernetes diagram

A Kubernetes diagram is most useful when it shows the objects rather than the machines: what an ingress routes to, which service selects which pods, and what namespace they live in.

Keep it beside the manifests. A cluster diagram in a different space is a cluster diagram nobody trusts.

---

## When to reach for one

* Explaining a deployment to people who will debug it.
* Reviewing a change to routing or scaling.
* Onboarding, where kubectl output is not yet a mental model.

---

## How to draw it in Capable

| **Route** | **Use when**                                                 |
| --------- | ------------------------------------------------------------ |
| Mermaid   | Object-level diagrams that live next to the manifests.       |
| D2        | Namespaces as containers, which reads well at cluster scale. |
| draw.io   | Presentation diagrams with official Kubernetes icons.        |

---

## A worked example

Ingress to service to pods, inside a namespace:

![Kubernetes diagram](https://help.gocapable.com/images/att1431044127.svg)

The source, which you can paste into a new diagram and edit:

```
flowchart TB
  EXT([Internet]) --> ING[Ingress: shop.example.com]
  subgraph NS[namespace: shop]
    ING --> SVCA[Service: web]
    ING --> SVCB[Service: api]
    SVCA --> P1[Pod: web-1]
    SVCA --> P2[Pod: web-2]
    SVCB --> P3[Pod: api-1]
    SVCB --> P4[Pod: api-2]
    P3 --> CM[(ConfigMap: api-config)]
    P3 --> SEC[(Secret: db-credentials)]
  end
  P3 --> DB[(Managed Postgres)]
```

---

## A few things that catch people out

* Draw services, not just pods. The service is the stable thing; pods come and go.
* Namespaces are the boundary that matters for network policy and RBAC.
* Do not draw replica counts as separate boxes unless the count is the point.

---

## Related

[CI/CD pipeline diagramCommit to production, with the gates visible.](https://help.gocapable.com/diagrams/ci-cd-pipeline-diagram.html)

[Cloud architecture diagramProvider icons, or text that lays itself out.](https://help.gocapable.com/diagrams/cloud-architecture-diagram.html)

[ExamplesWorking diagrams you can copy.](https://help.gocapable.com/diagrams/examples.html)

---

_Draw the trust boundary._