如何绘制 Kubernetes 架构图（附免费模板）

大多数 Kubernetes 图失败的方式无非两种：要么是一整面没人看得懂的 Pod 图标墙，要么是只写着“cluster”的三个方框草图，几乎没有其他信息。有用的 Kubernetes 架构图介于两者之间。它展示流量从哪里进入、由哪些对象路由、状态存放在哪里、哪些边界真正重要，并且详细程度要适合读图的人。

本指南介绍应该画什么、如何按受众选择详细程度、哪些错误会让架构图失去价值，以及如何在 Archboard 中一步步画出来。免费模板一键即可在你自己的工作区中作为新图打开。

一张好的 Kubernetes 架构图应展示什么

Kubernetes 文档介绍了 集群组件：control plane、kubelet、kube-proxy 等。这是平台视角。大多数团队需要的是工作负载视角：你的 应用如何在集群上运行。价值主要来自以下五点。

1. 集群与 namespace 边界

把集群画成最外层边界，把 namespace 画成其中的框。RBAC、resource quota 以及大多数 NetworkPolicy 都在 namespace 层面生效，因此这是大家最先问到的边界（“payments 有自己的 namespace 吗？”）。如果你运行多个集群（prod 和 staging，或每个区域一个），就为每个集群单独画边界，并标注名称和环境。

2. 南北向流量

展示请求从集群外部进入内部的路径：

Client → Ingress → Service → Deployment → Pods

用箭头明确方向。注明 Ingress 的主机和路径规则，以及 Service 的类型和端口。仅这一条路径，就能回答故障处理中大多数“这个请求去了哪里？”的问题。

东西向流量（集群内部服务之间的调用）同样重要，但要有选择地画：跨 namespace 的调用，或位于关键路径上的调用。

3. 配置与存储

把 ConfigMap、Secret 和 PersistentVolumeClaim 连接到使用它们的工作负载上。一个带有 Secret 和 PVC 的 Deployment 会告诉读者两件事：这个工作负载持有凭据，并且有比 Pod 生命周期更长的状态。把外部状态（例如托管的 Postgres）画在集群边界之外，清楚区分哪些归集群所有，哪些不是。

4. 扩缩容

把 HorizontalPodAutoscaler 放在它所作用的 Deployment 旁边，并在名称或备注中写明最小/最大副本数和指标（“2–10，CPU 70%”）。这比画十个 Pod 传达的信息更多。

5. NetworkPolicy

如果你使用 NetworkPolicy，就标出哪些策略生效、允许了什么。做安全评审的人希望直接看到“只有 api namespace 能访问 Postgres”，而不是靠推断。

清单如何对应到图中的节点

以三个普通对象为例：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: orders-api
  namespace: shop
spec:
  replicas: 3
  selector:
    matchLabels: { app: orders-api }
  template:
    metadata:
      labels: { app: orders-api }
    spec:
      containers:
        - name: api
          image: registry.example.com/orders-api:1.4.2
          ports: [{ containerPort: 8080 }]
          envFrom: [{ secretRef: { name: orders-db } }]
---
apiVersion: v1
kind: Service
metadata:
  name: orders-api
  namespace: shop
spec:
  selector: { app: orders-api }
  ports: [{ port: 80, targetPort: 8080 }]
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop
  namespace: shop
spec:
  rules:
    - host: shop.example.com
      http:
        paths:
          - path: /orders
            pathType: Prefix
            backend:
              service: { name: orders-api, port: { number: 80 } }

在图中，它们对应为：

三个副本对应一个标有“×3”的 Deployment 节点，而不是三个 Pod 方框。连线遵循 YAML 中的引用关系：Ingress backend → Service，Service selector → Deployment，envFrom → Secret。

按受众选择详细程度

一张图很少能满足所有人。动笔之前，先确定它是给谁看的。

如果两类受众需要的东西不同，就画两个视图，而不是用一张图包揽一切。

常见错误

• 把每个 Pod 副本都画出来。 副本是一个数字，不是架构。一个标注副本数的 Deployment 节点（如果会扩缩容，再加一个 HPA），比一排一模一样的方框更易读。
• 混用逻辑视图和物理视图。 工作节点、可用区和 Pod 的调度位置属于物理视图；Ingress → Service → Deployment 属于逻辑视图。把两者放在同一张画布上，哪个都看不清。需要物理视图时，单独画一张。
• 没有流量方向。 没有箭头的连线说明不了谁调用谁。使用有向连线，让主请求流保持单一方向：从左到右，或从上到下。
• 架构图过时。 一张还停留在去年服务状态的图，比没有图危害更大。在画布上写明负责人和“最近核对”日期，每当变更增加或删除了一个方框时就更新它。
• 连线没有说明。 “Service → Deployment”不言自明；但“orders-api → payments-api”应该写明协议和端口。

在 Archboard 中一步步绘制

Archboard 的 Kubernetes 节点包提供 33 种带端口的一等节点类型，从 Namespace（以 frame 形式绘制）、Node、Pod、Deployment、StatefulSet、Job 和 CronJob，到 Service、Ingress、Gateway API 路由、ConfigMap、Secret、PersistentVolumeClaim、HPA、NetworkPolicy 和 RBAC。你连接的是端口，而不是在通用形状之间画松散的线。你可以用 从 YAML 导入… 从清单开始，也可以手动放置每个节点；无论哪种方式，本指南讨论的“这里什么最重要？”这一判断都由你来做。

1. 研究示例。 打开 Kubernetes 微服务示例（Ingress → Service → Deployment/Pod → PVC → Postgres）和 Ingress 流量示例。留意布局：流量单向流动，状态位于末端。
2. 在工作区中新建一张图，为集群添加一个 Frame，以集群名称和环境命名。
3. 添加 Namespace： 为每个重要的 namespace 在集群框内放置一个 Namespace。
4. 摆放请求路径： 从左到右依次放 Ingress、Service、Deployment。端口对端口连接，并为主机/路径和端口添加简短的 Text 标签。
5. 连接配置与状态： 把 ConfigMap 和 Secret 放在读取它们的 Deployment 旁边，用 PVC 表示持久化存储，并在集群框外放一个数据库节点表示托管的 Postgres。
6. 添加扩缩容与策略： 在 Deployment 旁放一个写明最小/最大值和指标的 HPA，在受保护的 namespace 边界处放置 NetworkPolicy 节点。
7. 在画布上补充上下文： 用一个 Markdown 块写明负责人、最近核对日期，以及仓库或 runbook 的链接。画布上也支持代码块，因此关键的清单片段可以直接放在对应节点旁边。
8. 分享： 导出 SVG 或 PNG 放进设计文档，或者分享一个公开链接。自动保存和修订快照让你在改版出错时可以回退。

如果要在多账号视图中展示多个集群，可以使用 Cloud 包中的 Kubernetes Cluster 节点。

Free 套餐包含全部内置节点包，每张图最多 15 个图表节点，另加 150 个便签和文本，足够画一个服务的请求路径。完整的多服务架构图很可能需要 Pro。

免费模板

免费模板是 /templates/kubernetes-architecture：使用此模板 会在你的工作区中将其作为新图打开。如需更完整的布局，/examples/kubernetes-microservices 提供 使用此示例，可以复制这张图，方便你把节点重命名为自己的服务。如果只关心流量路径，/examples/kubernetes-ingress-flow 是一个更小的起点。更多模式请见 Kubernetes 使用场景页面。

常见问题

需要画 control plane 吗？ 只有当图的主题是平台本身时才需要，例如面向平台团队或升级计划。在应用架构图中，control plane 只是噪音；读者默认它存在。

画 Pod 还是 Deployment？ 画 Deployment，并标注副本数。只有当某个特定 Pod 很关键时才单独画 Pod：比如 sidecar 布局、一次调试会话，或一次 Job、CronJob 的运行。

如何让架构图保持最新？ 指定负责人，在画布上写明最近核对日期，并在修改相关服务的 pull request 中一并检查。架构图的 JSON 导出文件可以和清单一起放在仓库里。

一张图能覆盖多个集群吗？ 可以，但要提高抽象层级：每个集群一个边界，只画跨集群的流量。每个集群的细节放在单独的图中。

免费开始 — 1 个席位，无需信用卡