KubeDiagramsでKubernetesアーキテクチャ図を作成する

アーキテクチャ図の作成は面倒です。さらにそれを維持するのは腰の重い作業です。 特にKubernetesはアプリケーション独自の事情に合わせて構成が変わることも多く、その変化の速さに応じて図の更新も頻繁に発生します。

アーキテクチャ図は最新の状態であることに価値があり、また過去の履歴を保存しておいて比較できることも重要です。 アーキテクチャ図は自動生成しないとやってられない、ということでKubernetesのアーキテクチャ図を自動生成するツールを割と長く探していたのですが、最近使っているKubeDiagramsが良かったので紹介します。

KubeDiagramsとは

KubeDiagramsは、KubernetesリソースのYAMLマニフェストからアーキテクチャ図を自動生成するPython製ツールです。CLIツール・コンテナイメージ・GitHub Actionとして提供されており、環境に合わせて選択できます。

コマンドは2つあります。

• kube-diagrams : Kubernetesマニフェストからアーキテクチャ図を生成
• helm-diagrams : OCIレジストリを指定するとHelmチャートを取得しアーキテクチャ図を生成

手元のマニフェストから生成する場合はkube-diagramsを使い、公開されているHelmチャートの構成を確認する場合はhelm-diagramsを使います。

KubeDiagramsの嬉しいところ

コンフィグなしでレイアウトが作れる

KubeDiagramsは、特に設定ファイルを用意しなくても、Kubernetesマニフェストを指定するだけでアーキテクチャ図を生成できます。 ゼロコンフィグで使える図を生成できるのは、運用が楽で良いです。必要ならコンフィグを追加できるのも良いところです。

また、ラベル・アノテーションをもとにグルーピングできるので、YAMLマニフェストにラベルを追加しておくだけで運用と図の一貫性を保てます。

要素が増えてもレイアウトが破綻しない

アーキテクチャ図生成ツールの多くは、要素が増えた時にレイアウトが崩れるという共通の問題を抱えています。 KubeDiagramsは、要素が増えてもレイアウト崩れしにくいです。最高！

以下は公式ページにあるopen5gs-k8sのアーキテクチャ図です。多くの要素があるにもかかわらず、見やすいレイアウトになっています。

ラベル・アノテーションでグルーピング

KubeDiagramsは、Kubernetesリソースのラベル/アノテーションをもとにグルーピングして図を生成できます。 KubernetesのRecommended Labelsに沿って、以下が推奨されています。

ラベルキー	アーキテクチャ図上のタイトル	推奨
app.kubernetes.io/instance	K8s Instance: label value	YES
app.kubernetes.io/name	K8s Application: label value	YES
app.kubernetes.io/component	K8s Component: label	YES
helm.sh/chart	Helm Chart: label value	YES

以下は非推奨ですが利用できるラベルです。

ラベルキー	アーキテクチャ図上のタイトル	推奨
release	Release: label value	NO
chart	Chart: label value	NO
app	Application: label value	NO
tier	Tier: label value	NO
component	Component: label value	NO
service	Microservice: label value	NO

以下はアノテーションキーです。

アノテーションキー	アーキテクチャ図上のタイトル	推奨
helm.sh/hook	annotation value	YES

カスタムラベル/アノテーションを追加したい場合、簡単なコンフィグで指定できるのも嬉しいところです。

# KubeDiagrams.yaml
clusters:
  - label: k8s-app
    title: "K8s Application: {}"
  - label: kubernetes.io/bootstrapping
    title: "K8s Bootstrapping: {}"

次のように、実行時コンフィグファイルを指定すれば参照されます。

kube-diagrams -v -c KubeDiagrams.yaml -o diagram.png k8s-manifest.yaml

使い方

ローカルインストール以外に、コンテナイメージが利用できます。

2つあるコマンドのヘルプを見てみましょう。kube-diagramsコマンドのヘルプは次の通りです。

$ kube-diagrams -h
usage: kube-diagrams [-h] [-o OUTPUT] [-f FORMAT] [-c CONFIG] [-v] [--without-namespace] filename [filename ...]

Generate Kubernetes architecture diagrams from Kubernetes manifest files

positional arguments:
  filename              the Kubernetes manifest filename to process

options:
  -h, --help            show this help message and exit
  -o, --output OUTPUT   output diagram filename
  -f, --format FORMAT   output format, allowed formats are dot, dot_json, gif, jp2, jpe, jpeg, jpg, pdf, png, svg, tif, tiff, set to png by default
  --embed-all-icons     embed all icons into svg or dot_json output diagrams
  -c, --config CONFIG   custom kube-diagrams configuration file
  -n, --namespace NAMESPACE
                        visualize only the resources inside a given namespace
  -v, --verbose         verbosity, set to false by default
  --without-namespace   disable namespace cluster generation

helm-diagramsコマンドのヘルプは次の通りです。

$ helm-diagrams -h
Usage: helm-diagrams <helm-chart-url> [OPTIONS] [FLAGS]

A script to generate a diagram of an Helm chart using kube-diagrams.

Options:
  -o, --output <file>          Specify the output file for the diagram
  -f, --format <format>        Specify the output format (e.g., png, svg)
  --embed-all-icons            Embed all icons into svg or dot_json output diagrams
  -c, --config <file>          Specify the custom kube-diagrams configuration file
  -h, --help                   Display this help message

Any flag supported by helm template, e.g.:
  -g, --generate-name          Generate the name (and omit the NAME parameter)
  --include-crds               Include CRDs in the templated output
  -l, --labels stringToString  Labels that would be added to release metadata. Should be divided by comma. (default [])
  --name-template string       Specify template used to name the release
  --set stringArray            Set values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2)
  --set-file stringArray       Set values from respective files specified via the command line (can specify multiple or separate values with commas: key1=path1,key2=path2)
  --set-json stringArray       Set JSON values on the command line (can specify multiple or separate values with commas: key1=jsonval1,key2=jsonval2)
  --set-literal stringArray    Set a literal STRING value on the command line
  --set-string stringArray     Set STRING values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2)
  -f, --values strings         Specify values in a YAML file or a URL (can specify multiple)
  --version string             Specify a version constraint for the chart version to use. This constraint can be a specific tag (e.g. 1.1.1) or it may reference a valid range (e.g. ^2.0.0). If this is not specified, the latest version is used

Examples:
  helm-diagrams https://charts.jetstack.io/cert-manager -o diagram.png
  helm-diagrams https://charts.jetstack.io/cert-manager --set crds.enabled=true -o cert-manager.png
  helm-diagrams oci://ghcr.io/argoproj/argo-helm/argo-cd -f svg
  helm-diagrams --help

コンテナから利用する場合は、次のように実行します。PowerShellの場合は$(pwd)の部分を${PWD}に置き換えてください。

# kube-diagramsで直接マニフェストファイルを指定する場合
docker run -v "$(pwd)":/work philippemerle/kubediagrams kube-diagrams -o 画像.png マニフェスト.yaml

# マニフェストをパイプで受け取る場合は、-i と - （標準入力)を用いる
マニフェスト生成 | docker run -i -v "$(pwd)":/work philippemerle/kubediagrams kube-diagrams - -o 画像ファイル名.png

# OCIレジストリのHelmチャートから直接アーキテクチャ図を生成する場合
docker run -v "$(pwd)":/work philippemerle/kubediagrams helm-diagrams oci://URL -o 画像.png

マニフェストからアーキテクチャ図を生成する

KubeDiagramsは手元のマニフェストからアーキテクチャ図を生成できるので、CIで動かしやすく、PRに自動投稿したりと応用が利きます。 ツールのバージョン違いや依存関係のインストールを気にせず使うため、以降の例はコンテナイメージを用いて示します。

guitarrapc/argocd-labにある、C#、GoそれぞれでAPIサーバーを動作させる定義からアーキテクチャ図を生成してみましょう。C#、Goそれぞれについて、DeploymentとServiceがあるだけのシンプルな構成です。

手元にクローンして、KubeDiagramsを使ってアーキテクチャ図を生成する準備をします。

git clone https://github.com/guitarrapc/argocd-lab.git .
cd argocd-lab

Kubernetesマニフェストからアーキテクチャ図を生成する

まずは、k8s/api/deployment.yamlのマニフェストからアーキテクチャ図を生成します。

クリックでdeployment.yamlマニフェストを開く

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-csharp
  labels:
    app.kubernetes.io/name: api
    app.kubernetes.io/component: api-csharp
    app.kubernetes.io/part-of: api-application
spec:
  replicas: 1
  revisionHistoryLimit: 3
  selector:
    matchLabels:
      app: api-csharp
  template:
    metadata:
      labels:
        app: api-csharp
    spec:
      containers:
        - name: api-csharp
          image: ghcr.io/guitarrapc/argocd-lab:latest-csharp
          ports:
            - name: http
              containerPort: 8080
          livenessProbe:
            httpGet:
              path: /healthz
              port: http
          readinessProbe:
            httpGet:
              path: /healthz
              port: http
          resources:
            requests:
              memory: "128Mi"
              cpu: "250m"
            limits:
              memory: "256Mi"
              cpu: "500m"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-go
  labels:
    app.kubernetes.io/name: api
    app.kubernetes.io/component: api-go
    app.kubernetes.io/part-of: api-application
spec:
  replicas: 1
  revisionHistoryLimit: 3
  selector:
    matchLabels:
      app: api-go
  template:
    metadata:
      labels:
        app: api-go
    spec:
      containers:
        - name: api-go
          image: ghcr.io/guitarrapc/argocd-lab:latest-go
          ports:
            - name: http
              containerPort: 8080
          livenessProbe:
            httpGet:
              path: /healthz
              port: http
          readinessProbe:
            httpGet:
              path: /healthz
              port: http
          resources:
            requests:
              memory: "128Mi"
              cpu: "250m"
            limits:
              memory: "256Mi"
              cpu: "500m"
---
# no namespace declared here for argocd to manage it
apiVersion: v1
kind: Service
metadata:
  name: api-csharp-svc
  labels:
    app.kubernetes.io/name: api
    app.kubernetes.io/component: api-csharp
    app.kubernetes.io/part-of: api-application
spec:
  type: ClusterIP
  ports:
    - port: 80
      targetPort: http
  selector:
    app: api-csharp
---
apiVersion: v1
kind: Service
metadata:
  name: api-go-svc
  labels:
    app.kubernetes.io/name: api
    app.kubernetes.io/component: api-go
    app.kubernetes.io/part-of: api-application
spec:
  type: ClusterIP
  ports:
    - port: 80
      targetPort: http
  selector:
    app: api-go

docker経由でkube-diagramsコマンドを実行し、アーキテクチャ図を生成します。次のコマンドで、api.pngというファイル名で出力されます。

docker run -v "$(pwd)":/work philippemerle/kubediagrams kube-diagrams -o api.png k8s/api/deployment.yaml

あるいは、ローカルに配置することなくリモートから読ませてもいいでしょう。¹

curl https://raw.githubusercontent.com/guitarrapc/argocd-lab/609025cd5967d5bb7ce603d732da810b9e14b3e1/k8s/api/deployment.yaml | docker run -i -v "$(pwd)":/work philippemerle/kubediagrams kube-diagrams - -o api.png

アーキテクチャ図が生成されます。

Kustomizeからアーキテクチャ図を生成する

同様に、Kustomizeで構成されたマニフェストからもアーキテクチャ図を生成できます。 Kustomizeの出力をパイプで渡します。

k8s/kustomize-api/kustomization.yamlからアーキテクチャ図を生成する例です。

kubectlコマンドでKustomizeの出力を取得し、パイプで渡してアーキテクチャ図を生成します。

kubectl kustomize ./k8s/kustomize-api/ | docker run -i -v "$(pwd)":/work philippemerle/kubediagrams kube-diagrams - -o kustomize-api.png

あるいは、リモートから直接読ませることもできます。

kustomize build github.com/guitarrapc/argocd-lab/k8s/kustomize-api?ref=609025cd5967d5bb7ce603d732da810b9e14b3e1 | docker run -i -v "$(pwd)":/work philippemerle/kubediagrams kube-diagrams - -o kustomize-api.png

アーキテクチャ図が生成されます。

Helm Templateからアーキテクチャ図を生成する

手元でHelmチャートを作っている場合、helm templateの出力をパイプで渡してアーキテクチャ図を生成できます。

k8s/helm-apiからアーキテクチャ図を生成する例です。

helm templateの出力をパイプで渡してアーキテクチャ図を生成します。

helm template ./k8s/helm-api | docker run -i -v "$(pwd)":/work philippemerle/kubediagrams kube-diagrams - -o helm-api.png

アーキテクチャ図が生成されます。

Kubernetesクラスターからアーキテクチャ図を生成する

ここまではシンプルなマニフェストですが、今クラスターで動いているリソースを拾いたいということもあるでしょう。そんなときは、今稼働しているクラスターに対してkubectlで欲しい範囲のマニフェストを取得、パイプで渡してアーキテクチャ図を生成します。

kubectl get all --all-namespaces -o yaml | docker run -v "$(pwd)":/work -i philippemerle/kubediagrams kube-diagrams -o all-namespaces.png -

EKSでbookinfoアプリケーション、aws-secrets-store-csi-driver、metrics-serverを動かしている場合、次のようなアーキテクチャ図が生成されます。

マニフェストから動作状況を直感的に把握することは難しいです。KubeDiagramsを使うと、今どんなリソースが動いているかをアーキテクチャ図でパッと確認できるのがうれしいところです。

Helmチャートからアーキテクチャ図を生成する

OCIレジストリに公開されているHelmチャートから直接アーキテクチャ図を生成できます。インストールすることなく、リソース全体像が把握できるのは便利です。

ArgoCDのHelmチャートからアーキテクチャ図を生成してみましょう。

docker run -v "$(pwd)":/work philippemerle/kubediagrams helm-diagrams oci://ghcr.io/argoproj/argo-helm/argo-cd -o argocd.png

次のようなアーキテクチャ図が生成されます。

--setや-fでhelmの値を指定することで、実際に使う構成に近い形でアーキテクチャ図を生成できます。便利！

まとめ

KubeDiagramsは、Kubernetesマニフェストからアーキテクチャ図を自動生成できる便利なツールです。 ゼロコンフィグで使えるので運用が楽で、グループ表示もラベル・アノテーションで制御できるため、多くのアーキテクチャ図を出したいというニーズにすぐ応えられます。

最近は、awslabs/diagram-as-codeやDiagram Generator | aws-samples/bedrock-engineerのようにAIを使ったアーキテクチャ図生成ツールが出てきています。Kubernetesも管理ダッシュボード上でAIを動かすのが流行りつつあり、kubectl-aiのようにKubernetesリソースをAIで解析するツールも登場しています。

KubeDiagramsも将来的にAIを活用した機能が追加されると面白そうです。現時点で便利なツールですので、ぜひ試してみてください。オススメです。

参考

GitHub

• philippemerle/KubeDiagrams | GitHub
• guitarrapc/argocd-lab | GitHub
• niloysh/open5gs-k8s | GitHub
• kubernetes-sample-apps/bookinfo-example at master · digitalocean/kubernetes-sample-apps | GitHub
• awslabs/diagram-as-code | GitHub
• aws-samples/bedrock-engineer | GitHub
• GoogleCloudPlatform/kubectl-ai | GitHub

Kubernetesドキュメント

• Recommended Labels | Kubernetes

Artifact Hub

• argo-cd argoproj/argo | Artifact Hub

---

1. APIレート制限やアクセス制限を考えることになるので、可能ならローカルマニフェストから生成するほうが楽です。↩