Kubernetes 構成図の描き方（無料テンプレート付き）

Kubernetes の図は、たいてい次のどちらかで失敗します。誰も読めない Pod アイコンの壁になるか、「cluster」と書かれた 3 つの箱だけのスケッチで終わるかです。役に立つ Kubernetes 構成図はその中間にあります。トラフィックがどこから入り、どのオブジェクトがそれをルーティングし、状態(ステート)がどこにあり、どの境界が重要なのかを、読む人に合った詳細度で示します。

このガイドでは、何を描くべきか、読み手に応じて詳細度をどう選ぶか、図を役に立たなくするよくある間違い、そして Archboard でステップごとに描く方法を説明します。無料テンプレートは、ワンクリックで自分のワークスペースに新しい図として開けます。

良い Kubernetes 構成図が示すもの

Kubernetes のドキュメントでは クラスターのコンポーネント(control plane、kubelet、kube-proxy など)が説明されています。これはプラットフォームの視点です。多くのチームに必要なのはワークロードの視点、つまり 自分たちの アプリケーションがクラスター上でどう動いているかです。価値の大部分は次の 5 つが担います。

1. クラスターと namespace の境界

クラスターを外側の境界として、namespace をその中のフレームとして描きます。RBAC、resource quota、そして多くの NetworkPolicy は namespace 単位で適用されるため、真っ先に聞かれるのはこの境界です(「payments は専用の namespace にありますか?」)。複数のクラスターを運用している場合(prod と staging、あるいはリージョンごと)は、それぞれに境界を設け、名前と環境を書き込みます。

2. North-south トラフィック

リクエストの経路を、クラスターの外側から内側へ向かって示します。

Client → Ingress → Service → Deployment → Pods

方向は矢印ではっきり示します。Ingress のホストとパスのルール、Service のタイプとポートを書き添えます。この 1 本の経路だけで、インシデント中の「このリクエストはどこへ行くのか?」という疑問の多くに答えられます。

East-west トラフィック(クラスター内のサービス間通信)も重要ですが、描くのは選んだものだけにします。namespace をまたぐ呼び出しや、クリティカルパス上の呼び出しです。

3. 設定とストレージ

ConfigMap、Secret、PersistentVolumeClaim は、それを使うワークロードに接続します。Secret と PVC を持つ Deployment からは、このワークロードが認証情報を扱うこと、そして Pod より長く残る状態を持つことの 2 点が読み取れます。マネージドの Postgres などの外部の状態はクラスター境界の外に描き、クラスターが所有するものとそうでないものを明確にします。

4. スケーリング

HorizontalPodAutoscaler は対象の Deployment の隣に置き、最小/最大レプリカ数とメトリクスを名前かメモに書きます(「2–10、CPU 70%」)。10 個の Pod を描くよりも多くを伝えられます。

5. NetworkPolicy

NetworkPolicy を使っている場合は、どれが適用され、何を許可しているかを示します。セキュリティレビューの担当者は「Postgres に到達できるのは api namespace だけ」という事実を推測ではなく図で確認したいのです。

マニフェストを図のノードに対応させる

ごく普通の 3 つのオブジェクトを例にします。

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 つのレプリカは 3 つの Pod の箱ではなく、「×3」と書いた 1 つの Deployment ノードになります。エッジは YAML 内の参照に従います。Ingress の backend → Service、Service の selector → Deployment、envFrom → Secret です。

読み手に合わせて詳細度を選ぶ

1 枚の図で全員の役に立つことはめったにありません。描き始める前に、誰のための図かを決めます。

読み手によって必要なものが違う場合は、すべてを詰め込んだ 1 枚ではなく、2 つのビューを描きます。

よくある間違い

• Pod のレプリカをすべて描く。 レプリカは数値であり、アーキテクチャではありません。レプリカ数を書いた 1 つの Deployment ノード(スケールするなら HPA も)のほうが、同じ箱が並んだグリッドより読みやすくなります。
• 論理と物理を混ぜる。 ワーカーノード、ゾーン、Pod の配置は物理ビューで、Ingress → Service → Deployment は論理ビューです。1 つのキャンバスに両方を載せると、どちらも読めなくなります。物理ビューが必要なら別の図にします。
• トラフィックの向きがない。 矢印のない線では、誰が誰を呼んでいるのかがわかりません。有向エッジを使い、メインのリクエストの流れを左から右、または上から下の一方向にそろえます。
• 図が古くなる。 昨年のサービス構成のままの図は、図がないよりも害があります。キャンバスにオーナーと「最終確認日」を書き、箱が増えたり減ったりする変更があれば更新します。
• エッジに説明がない。 「Service → Deployment」は自明ですが、「orders-api → payments-api」にはプロトコルとポートを書くべきです。

Archboard でステップごとに描く

Archboard の Kubernetes パックには、ポートを持つ正式なノードタイプが 33 種類あります。Namespace（フレームとして描画）、Node、Pod、Deployment、StatefulSet、Job、CronJob から、Service、Ingress、Gateway API のルート、ConfigMap、Secret、PersistentVolumeClaim、HPA、NetworkPolicy、RBAC までそろっています。汎用の図形の間にばらばらの線を引くのではなく、ポート同士をつなぎます。YAML からインポート… でマニフェストから始めることも、ノードを 1 つずつ手で配置することもできます。どちらの場合も、このガイドのテーマである「ここで何が重要か」という判断を下すのはあなた自身です。

1. サンプルを確認する。 Kubernetes マイクロサービスのサンプル(Ingress → Service → Deployment/Pod → PVC → Postgres)と Ingress フローのサンプル を開きます。トラフィックが一方向に流れ、状態が末端にあるレイアウトに注目してください。
2. ワークスペースで図を作成し、クラスター用の Frame を追加して、クラスター名と環境の名前を付けます。
3. Namespace を追加する。 重要な namespace ごとに、クラスターのフレームの中に配置します。
4. リクエスト経路を配置する。 Ingress、Service、Deployment の順に左から右へ並べます。ポート同士を接続し、ホスト/パスとポートを短い Text ラベルで書き添えます。
5. 設定と状態をつなぐ。 ConfigMap と Secret はそれを読み込む Deployment の隣に、永続ストレージ用に PVC を、マネージドの Postgres 用にクラスターのフレームの外にデータベースノードを置きます。
6. スケーリングとポリシーを加える。 Deployment の隣に最小/最大とメトリクスを書いた HPA を、保護する namespace の境界に NetworkPolicy ノードを置きます。
7. キャンバスに文脈を書き込む。 オーナー、最終確認日、リポジトリや runbook へのリンクを Markdown ブロックにまとめます。キャンバス上ではコードブロックも使えるので、重要なマニフェストの抜粋を対応するノードの隣に置けます。
8. 共有する。 設計ドキュメント用に SVG または PNG でエクスポートするか、公開リンクを共有します。自動保存とリビジョンのスナップショットがあるので、手直しがうまくいかなくても元に戻せます。

複数のクラスターをマルチアカウントで俯瞰する場合は、Cloud パックの Kubernetes Cluster ノードを使えます。

Free プランではすべての組み込みパックを使え、1 つの図にダイアグラムノードを 15 個、さらにメモ・テキストを 150 件まで置けます。1 つのサービスのリクエスト経路なら収まります。複数サービスを網羅したマップには、おそらく Pro が必要です。

無料テンプレート

無料テンプレートは /templates/kubernetes-architecture です。このテンプレートを使う で、自分のワークスペースに新しい図として開けます。より充実したレイアウトが必要なら、/examples/kubernetes-microservices の この事例を使う でコピーし、ノード名を自分のサービス名に変更できます。トラフィック経路だけなら、より小さな /examples/kubernetes-ingress-flow から始めるのがおすすめです。その他のパターンは Kubernetes のユースケースページ にまとめています。

よくある質問

control plane は描くべきですか? 図がプラットフォームそのものを扱う場合だけです。たとえばプラットフォームチーム向けや、アップグレード計画などです。アプリケーションの図では control plane はノイズで、読み手はその存在を前提にしています。

Pod と Deployment のどちらを描くべきですか? レプリカ数を添えた Deployment です。個々の Pod を描くのは、特定の Pod が重要な場合に限ります。サイドカーの構成、デバッグ中のセッション、Job や CronJob の実行などです。

図を最新に保つにはどうすればよいですか? オーナーを決め、キャンバスに最終確認日を書き、図に描かれたサービスを変更する pull request と合わせて見直します。図の JSON エクスポートを、マニフェストと一緒にリポジトリに置いておくこともできます。

1 枚の図で複数のクラスターを扱えますか? はい、抽象度を上げれば可能です。クラスターごとに境界を 1 つ設け、クラスター間のトラフィックだけを描きます。クラスターごとの詳細は別の図に分けます。

無料で始める — 1 シート、クレジットカード不要