@k2works/claude-code-booster 4.6.0 → 4.7.0

package/lib/assets/docs/article/getting-start-docker-kubernetes/15-case-escqrs-axon-kustomize-vs-helm.md

@@ -0,0 +1,288 @@
+# 第 15 章 ES/CQRS マイクロサービス（Axon）のデプロイ — Kustomize 対 Helm
+
+## はじめに
+
+前章では、イベント連携を RabbitMQ で行うイベント駆動マイクロサービス（case-2）を Kustomize と Helm で比較しました。この章では、同じ国際貨物輸送システム（Cargo Tracker）を **Axon Framework によるイベントソーシング / CQRS（ES/CQRS）** で実装した版（case-3）を取り上げます。
+
+比較軸は引き続き **Kustomize 対 Helm** です。case-2 との最大の違いは、サービス間連携の基盤が **Axon Server**（イベントストア兼コマンド/イベントルーター）になる点です。この「特別な単発インフラ」が加わることで、両手段の書き分けがどう変わるかを確認します。
+
+実装は [`apps/case-studies/case-3-escqrs-axon/`](https://github.com/k2works/getting-started-docker-kubernetes/tree/main/apps/case-studies/case-3-escqrs-axon) にあります。
+
+---
+
+## 1. アーキテクチャ概要
+
+ES/CQRS では、状態変更を「イベント」として記録（イベントソーシング）し、書き込み（Command）と読み取り（Query）のモデルを分離（CQRS）します。Axon Framework はこのパターンを実装するためのフレームワークで、**Axon Server** がイベントストアとメッセージルーティングを担います。
+
+```plantuml
+@startuml
+title ES/CQRS（Axon）版 Cargo Tracker
+
+actor 利用者
+node "frontend (nginx)" as fe
+node "gatewayms :8080" as gw
+node "authms :8081" as auth
+node "bookingms :8082" as booking
+node "routingms :8083" as routing
+node "trackingms :8086" as tracking
+node "billingms :8087" as billing
+node "Axon Server\n:8124 gRPC / :8024 HTTP" as axon
+database "PostgreSQL\n(6 read DB)" as db
+
+利用者 --> fe
+fe --> gw
+gw --> auth
+gw --> booking
+gw --> routing
+gw --> tracking
+gw --> billing
+booking <--> axon : command/event
+routing <--> axon
+tracking <--> axon
+billing <--> axon
+booking --> db : read model
+tracking --> db
+billing --> db
+@enduml
+```
+
+構成要素は次のとおりです。
+
+- **gatewayms**（8080）: API ゲートウェイ
+- **authms**（8081）: 認証（JWT 発行）。DB のみで Axon は使わない
+- **bookingms**(8082)・**routingms**(8083)・**handlingms**(8085)・**trackingms**(8086)・**billingms**(8087): ES/CQRS サービス。Axon Server を利用
+- **Axon Server**（8124 gRPC / 8024 HTTP）: イベントストア・ルーティング（standalone + DCB モード）
+- **PostgreSQL**: 1 インスタンスに 6 つの **read DB**（CQRS の Read 側射影）
+- **frontend**: SPA
+
+case-2 の RabbitMQ が「メッセージブローカー」だったのに対し、Axon Server は「イベントストア + ルーター」という、より中心的でステートフルな役割を持ちます。
+
+### イメージのビルド
+
+case-3 の各サービス Dockerfile はマルチステージ（コンテナ内で Gradle ビルド）で自己完結しています。
+
+```bash
+cd apps/case-studies/case-3-escqrs-axon/backend
+for s in gatewayms authms bookingms routingms trackingms handlingms billingms; do
+  docker build -t "cargo3-$s:0.0.1" -f "$s/Dockerfile" .
+done
+cd ../frontend && docker build -t cargo3-frontend:0.0.1 .
+```
+
+---
+
+## 2. Kustomize による実装
+
+`apps/case-studies/case-3-escqrs-axon/k8s/kustomize/base/` の構成です。
+
+```
+base/
+├── kustomization.yaml
+├── namespace.yaml
+├── secret.yaml             # DB 認証 + JWT_SECRET
+├── init-databases.sh       # POSTGRES_MULTIPLE_DATABASES 用初期化（ConfigMap 化）
+├── postgres.yaml           # 6 read DB を初期化する PostgreSQL
+├── axonserver.yaml         # ★ Axon Server（standalone + DCB）
+├── authms.yaml             # DB + JWT
+├── bookingms.yaml          # ┐
+├── routingms.yaml          # │ Axon サービス（DB + AXON_AXONSERVER_SERVERS）
+├── handlingms.yaml         # │
+├── trackingms.yaml         # │
+├── billingms.yaml          # ┘
+├── gatewayms.yaml
+├── frontend.yaml
+└── ingress.yaml
+```
+
+case-2 との違いは 2 点です。
+
+**(1) Axon Server という単発インフラ**。`axonserver.yaml` に、standalone + DCB モードを有効化する環境変数を持つ Deployment と、gRPC(8124)/HTTP(8024) を公開する Service を定義します。
+
+```yaml
+          image: axoniq/axonserver:2026.0.0
+          env:
+            - name: AXONIQ_AXONSERVER_STANDALONE
+              value: "true"
+            - name: AXONIQ_AXONSERVER_STANDALONE_DCB
+              value: "true"
+          ports:
+            - { name: http, containerPort: 8024 }
+            - { name: grpc, containerPort: 8124 }
+```
+
+**(2) Axon を使うサービスだけ接続先を渡す**。Axon サービス（5 つ）には `AXON_AXONSERVER_SERVERS=axonserver:8124` を追加しますが、authms には付けません。Kustomize ではこの差を、サービスごとのファイルに env を「書く / 書かない」で表現します。
+
+```yaml
+# bookingms.yaml（Axon あり）
+            - name: AXON_AXONSERVER_SERVERS
+              value: axonserver:8124
+# authms.yaml（Axon なし、代わりに JWT）
+            - name: JWT_SECRET
+              valueFrom: { secretKeyRef: { name: app-secrets, key: JWT_SECRET } }
+```
+
+PostgreSQL の複数 DB は、`POSTGRES_MULTIPLE_DATABASES` 環境変数と初期化スクリプト（`init-databases.sh` を ConfigMap 化して `/docker-entrypoint-initdb.d` にマウント）で作成します。
+
+### デプロイと動作確認
+
+```bash
+kubectl apply -k apps/case-studies/case-3-escqrs-axon/k8s/kustomize/base
+```
+
+postgres + axonserver + 6 サービス + gateway + frontend の **10 Pod** がすべて `1/1 Running` になります。Axon サービスは Axon Server の起動を待つため、起動初期に再起動が入りますが、`readinessProbe` の範囲で復帰します。
+
+```bash
+# Axon Server の HTTP ヘルス
+kubectl -n cargo-axon port-forward svc/axonserver 18024:8024
+curl -s -o /dev/null -w '%{http_code}\n' http://localhost:18024/actuator/health   # 200
+
+# ゲートウェイ経由の疎通
+kubectl -n cargo-axon port-forward svc/gatewayms 18093:8080
+curl http://localhost:18093/actuator/health                       # {"status":"UP"}
+curl -s -o /dev/null -w '%{http_code}\n' http://localhost:18093/api/v1/bookings/   # 401（bookingms に到達）
+```
+
+`/api/v1/...` が `401`（認証要求）や `404`（パス未定義）を返すことは、ゲートウェイが各 ES/CQRS サービスに到達できている証拠です。
+
+---
+
+## 3. Helm による実装
+
+`apps/case-studies/case-3-escqrs-axon/helm/cargo-axon/` の構成です。
+
+```
+helm/cargo-axon/
+├── Chart.yaml
+├── values.yaml
+├── init-databases.sh
+└── templates/
+    ├── infra.yaml          # secret + postgres-init + postgres + axonserver
+    ├── microservices.yaml  # 6 サービスをループ生成（axon/jwt を条件分岐）
+    ├── gateway.yaml
+    ├── frontend.yaml
+    └── ingress.yaml
+```
+
+case-2 と同様、6 サービスを `values.yaml` のリスト + テンプレートのループに集約します。さらに **Axon の要否・JWT の要否をフラグで条件分岐**できる点が、この構成での Helm の強みを示します。
+
+`values.yaml`：
+
+```yaml
+services:
+  - name: authms
+    port: 8081
+    database: auth_db
+    axon: false
+    jwt: true
+  - name: bookingms
+    port: 8082
+    database: booking_read_db
+    axon: true
+    jwt: false
+  # ... routing / handling / tracking / billing（すべて axon: true）
+```
+
+`templates/microservices.yaml`（抜粋）：
+
+```yaml
+{{- range .Values.services }}
+          env:
+            - name: SPRING_DATASOURCE_URL
+              value: jdbc:postgresql://postgres:5432/{{ .database }}
+            {{- if .axon }}
+            - name: AXON_AXONSERVER_SERVERS
+              value: axonserver:8124
+            {{- end }}
+            {{- if .jwt }}
+            - name: JWT_SECRET
+              valueFrom: { secretKeyRef: { name: app-secrets, key: JWT_SECRET } }
+            {{- end }}
+{{- end }}
+```
+
+Kustomize では「Axon あり / なし」「JWT あり / なし」をファイルごとに手で書き分けていましたが、Helm では `axon: true/false`・`jwt: true/false` というデータと `{{- if }}` の条件分岐で表現できます。**サービスの性質をデータとして宣言し、テンプレートが構造を生成する**わけです。
+
+Axon Server のような単発インフラは、`infra.yaml` に固定で記述します（ループ化しても 1 個なので利点が薄いため）。ここは Kustomize の `axonserver.yaml` とほぼ同じ記述になります。
+
+### 検証とデプロイ
+
+```bash
+helm lint apps/case-studies/case-3-escqrs-axon/helm/cargo-axon
+# 1 chart(s) linted, 0 chart(s) failed
+
+helm install cargo-axon apps/case-studies/case-3-escqrs-axon/helm/cargo-axon \
+  --namespace cargo-axon --create-namespace
+```
+
+Helm 版も 10 Pod が `1/1 Running` になり、Axon Server のヘルス・ゲートウェイ経由の疎通（health UP、`/api/v1/...` が 401）を確認できました。
+
+---
+
+## 4. ロギング基盤（EFK + DaemonSet）
+
+[第 9 章](09-container-operations.md) の **EFK（Elasticsearch + Fluentd + Kibana）+ DaemonSet** によるログ集約パターンを、本ケースにも実装として組み込んでいます（[第 13 章](13-case-monolith-compose-vs-kustomize.md) と同じ構成）。各 Pod は標準出力にログを出すだけで、各ノードに常駐する Fluentd がノード上の全 Pod のログを収集し、Elasticsearch に蓄積、Kibana で可視化します。
+
+`k8s/kustomize/base/logging/` に 4 ファイルを置き、`kustomization.yaml` の `resources` に追加しています。
+
+```
+logging/
+├── elasticsearch.yaml      # ConfigMap + PVC + Service + Deployment（単一ノード）
+├── fluentd-daemonset.yaml  # ServiceAccount + ClusterRole/Binding + DaemonSet
+├── kibana.yaml             # Deployment + Service（NodePort 30053）
+└── kibana-setup-job.yaml   # index pattern logstash-* を自動作成する Job
+```
+
+実装上の勘所は第 13 章と共通です。
+
+- **Fluentd**: `hostPath` で `/var/log/containers` を読み取る。containerd の CRI ログ形式に合わせて `FLUENT_CONTAINER_TAIL_PARSER_TYPE` を指定（既定の json だと不一致）。ClusterRole はケース間で衝突しないよう `fluentd-cargo-axon` に修飾
+- **Elasticsearch**: RWO PVC のため `strategy: Recreate`、heap の 3〜4 倍（2Gi）のメモリ上限で OOM を回避
+- **Kibana**: `kibana-setup` Job が index pattern と既定ビュー（Discover）を自動設定し、開いたらすぐ使える
+
+ES/CQRS 構成では、Axon Server を含む各サービスのアプリログ（Fluentd → Kibana）と、イベントストアそのものの状態（Axon Server ダッシュボード）を併用すると、コマンド・イベントの流れを多面的に追えます。
+
+```bash
+# アプリと同時にデプロイされる（kubectl apply -k k8s/kustomize/base）
+kubectl -n cargo-axon get pods -l app.kubernetes.io/component=logging
+kubectl -n cargo-axon exec deploy/elasticsearch -- curl -s 'http://localhost:9200/logstash-*/_count'
+# Kibana を開く（kind では NodePort が localhost に出ないため port-forward が確実）
+kubectl -n cargo-axon port-forward svc/kibana 18081:5601   # → http://localhost:18081/
+```
+
+---
+
+## 5. 比較考察
+
+ES/CQRS（Axon）という構成で、Kustomize と Helm の差は次のように整理できます。
+
+| 観点 | Kustomize | Helm |
+|------|-----------|------|
+| 同型サービスの繰り返し | サービスごとにファイル（6 ファイル） | `values` のリスト + ループ |
+| サービスの性質差（Axon/JWT） | ファイルに env を書く / 書かない | `axon`/`jwt` フラグ + `{{- if }}` |
+| 単発インフラ（Axon Server） | 専用ファイル | テンプレートに固定記述（ループの利点は薄い） |
+| 複数 DB 初期化 | `configMapGenerator` でスクリプトを ConfigMap 化 | `.Files.Get` でスクリプトを取り込み |
+| リリース管理 | なし | リビジョン・ロールバック |
+
+この章の要点は、**「繰り返し」と「単発」の混在をどう扱うか**です。
+
+- **繰り返し（6 つの ES/CQRS サービス）**: Helm のループ + フラグ条件分岐が明確に有利です。サービスごとの差（Axon/JWT の要否）をデータで表現でき、新しいサービスの追加も `values` への 1 エントリで済みます。
+- **単発インフラ（Axon Server・PostgreSQL）**: ループの恩恵がないため、Kustomize と Helm で記述量はほぼ同じです。Helm でも `infra.yaml` に素直に書きます。
+
+つまり、**システムに同型コンポーネントが多いほど Helm のテンプレート化が効き、単発リソースが多いほど両者の差は縮まります**。Axon のような ES/CQRS では「Axon を使うサービス群」という同型の繰り返しが生じやすく、Helm のフラグによる条件分岐が読みやすさと保守性に寄与します。
+
+一方、Axon Server の設定（standalone・DCB など）のような**繊細で固有の設定は、生 YAML に近い Kustomize のほうが意図を追いやすい**という見方もできます。
+
+---
+
+## まとめ
+
+- ES/CQRS（Axon）版 Cargo Tracker（Axon Server + 6 サービス + PostgreSQL〔6 read DB〕+ gateway + frontend）を Kustomize と Helm の両方でデプロイし、いずれも 10 Pod が `1/1 Running`、Axon Server ヘルス 200、ゲートウェイ経由の疎通を確認しました
+- 同型サービスの「性質の差」（Axon/JWT の要否）を、Kustomize はファイルの書き分けで、Helm は `values` のフラグ + `{{- if }}` で表現します
+- 単発インフラ（Axon Server）は、どちらの手段でも記述量はほぼ同じです
+- 第 9 章の EFK + DaemonSet を本ケースにも組み込み、Axon Server を含む各サービスのログを Fluentd（DaemonSet）→ Kibana で一元的に観測できるようにしました
+- 次章では、同じ ES/CQRS を Kafka で実装した case-4 を題材に、引き続き Kustomize と Helm を比較します
+
+---
+
+- 前の章: [第 14 章 イベント駆動マイクロサービスのデプロイ — Kustomize 対 Helm](14-case-event-driven-kustomize-vs-helm.md)
+- 次の章: [第 16 章 ES/CQRS マイクロサービス（Kafka）のデプロイ — Kustomize 対 Helm](16-case-escqrs-kafka-kustomize-vs-helm.md)
+- シリーズ目次: [Docker/Kubernetes 実践コンテナ解説](index.md)

package/lib/assets/docs/article/getting-start-docker-kubernetes/16-case-escqrs-kafka-kustomize-vs-helm.md

@@ -0,0 +1,247 @@
+# 第 16 章 ES/CQRS マイクロサービス（Kafka）のデプロイ — Kustomize 対 Helm
+
+## はじめに
+
+前章では ES/CQRS を Axon Framework（専用イベントストア Axon Server）で実装した case-3 を比較しました。この章では、同じ ES/CQRS を **Kafka をイベントバックボーン**として実装した版（case-4）を取り上げます。比較軸は引き続き **Kustomize 対 Helm** です。
+
+case-4 は、これまでの章で手づくりしてきたものより**実運用に近い完成度のデプロイ資産**を持っています。Kustomize には `base` と `overlays/`（local・prod）の階層があり、Helm には `_helpers.tpl` による命名・ラベルの共通化があります。本章では、この成熟した両構成を比較します。
+
+実装は [`apps/case-studies/case-4-escqrs-kafka/`](https://github.com/k2works/getting-started-docker-kubernetes/tree/main/apps/case-studies/case-4-escqrs-kafka) にあります。
+
+---
+
+## 1. アーキテクチャ概要
+
+case-3（Axon）が専用のイベントストアを使うのに対し、case-4 は汎用の **Kafka + ZooKeeper** をイベントストリーミング基盤に使います。
+
+```plantuml
+@startuml
+title ES/CQRS（Kafka）版 Cargo Tracker
+
+actor 利用者
+node "frontendms (nginx)" as fe
+node "gatewayms :8080" as gw
+node "authms / bookingms / routingms\ntrackingms / handlingms / billingms" as ms
+queue "Kafka :9092\n+ ZooKeeper" as kafka
+database "PostgreSQL\n(read DB)" as db
+
+利用者 --> fe
+fe --> gw
+gw --> ms
+ms <--> kafka : produce/consume events
+ms --> db : read model
+@enduml
+```
+
+構成要素は次のとおりです。
+
+- **gatewayms**（8080）: API ゲートウェイ（`/api/auth/**`・`/api/v1/bookings/**` などをルーティング）
+- **6 マイクロサービス**: authms(8081)・bookingms(8082)・routingms(8083)・trackingms(8084)・handlingms(8085)・billingms
+- **frontendms**: SPA（nginx）
+- **Kafka**（9092 / 内部 29092）+ **ZooKeeper**: イベントストリーミング
+- **PostgreSQL**: CQRS の read モデル DB
+
+Kafka・ZooKeeper・PostgreSQL は **StatefulSet**、各サービス・frontendms は **Deployment** としてデプロイされます。
+
+### イメージのビルド
+
+各サービス・frontend はマルチステージ Dockerfile（Java 21）で自己完結しています。
+
+```bash
+cd apps/case-studies/case-4-escqrs-kafka
+for s in gatewayms authms bookingms routingms trackingms handlingms billingms; do
+  docker build -t "cargo-tracker/$s:latest" -f "backend/$s/Dockerfile" backend
+done
+docker build -t cargo-tracker/frontendms:latest frontend
+```
+
+---
+
+## 2. Kustomize による実装（base + overlays）
+
+これまでの章では `base` のみでしたが、case-4 は **overlay** を備えます。
+
+```
+k8s/
+├── base/
+│   ├── kustomization.yaml   # 全リソース + images（イメージタグ集中管理）
+│   ├── namespace.yaml / configmap.yaml / secret.yaml
+│   ├── zookeeper.yaml / kafka.yaml / postgresql.yaml   # StatefulSet
+│   ├── authms.yaml … billingms.yaml / gatewayms.yaml / frontendms.yaml
+│   └── ingress.yaml
+└── overlays/
+    ├── local/kustomization.yaml   # ローカル検証用
+    └── prod/kustomization.yaml    # 本番用
+```
+
+`base` が共通定義、`overlays/<env>` が環境ごとの差分です。ローカル用 overlay は、`base` を参照しつつ gatewayms の Service を NodePort に**パッチ**します。
+
+```yaml
+# overlays/local/kustomization.yaml
+resources:
+  - ../../base
+patches:
+  - target:
+      kind: Service
+      name: gatewayms
+    patch: |-
+      - op: replace
+        path: /spec/type
+        value: NodePort
+      - op: add
+        path: /spec/ports/0/nodePort
+        value: 30080
+```
+
+これが第 13 章で触れた「base + overlay」の実例です。環境差分を**パッチとして宣言**し、base には一切手を加えません。本番用 overlay では、レプリカ数やリソース、Ingress ホストなどを別途上書きします。
+
+`base/kustomization.yaml` の `images` でイメージタグを集中管理する点は、これまでの章と同じです。
+
+### デプロイと動作確認
+
+overlay を指定して適用します。
+
+```bash
+kubectl apply -k apps/case-studies/case-4-escqrs-kafka/k8s/overlays/local
+```
+
+Kafka・ZooKeeper・PostgreSQL（StatefulSet）+ 6 サービス + gateway + frontendms の **11 ワークロード**がすべて `1/1 Running` になります。Kafka の起動を待つため、サービスに起動初期の再起動が入りますが復帰します。
+
+ゲートウェイ経由の疎通を、正しいルートパスで確認します。
+
+```bash
+kubectl -n cargo-tracker port-forward svc/gatewayms 18096:8080
+curl http://localhost:18096/actuator/health
+# {"status":"UP","groups":["liveness","readiness"]}
+
+curl -s -o /dev/null -w '%{http_code}\n' http://localhost:18096/api/v1/bookings   # 200
+curl -s -o /dev/null -w '%{http_code}\n' http://localhost:18096/api/v1/voyages    # 200
+curl -s -o /dev/null -w '%{http_code}\n' http://localhost:18096/api/v1/tracking   # 200
+curl -s -o /dev/null -w '%{http_code}\n' -X POST http://localhost:18096/api/auth/login  # 400（authms 到達）
+curl -s -o /dev/null -w '%{http_code}\n' http://localhost:18096/nope               # 404（ルートなし）
+```
+
+read 系エンドポイントが **200** を返すことは、Kafka 経由でイベントが配信され CQRS の read モデルが構築され、ゲートウェイ→サービス→DB が一貫して動作している証拠です。
+
+---
+
+## 3. Helm による実装（_helpers.tpl + microservices ループ）
+
+`helm/cargo-tracker/` の構成です。
+
+```
+helm/cargo-tracker/
+├── Chart.yaml
+├── values.yaml
+└── templates/
+    ├── _helpers.tpl       # 命名・共通ラベルのヘルパー
+    ├── config.yaml        # ConfigMap + Secret
+    ├── infra.yaml         # zookeeper / kafka / postgresql（StatefulSet）
+    ├── microservices.yaml # サービスをループ生成
+    ├── frontend.yaml
+    └── ingress.yaml
+```
+
+これまでの章の Helm チャートと同様、サービスは `values.yaml` のリスト + ループで生成します。case-4 の `values.yaml` は、サービスごとの差（ポート・DB・JWT・追加 Secret 環境変数）をデータで表現します。
+
+```yaml
+microservices:
+  - name: authms
+    port: 8081
+    db: auth_db
+    jwt: true
+  - name: bookingms
+    port: 8082
+    db: booking_read_db
+  - name: trackingms
+    port: 8084
+    db: tracking_read_db
+    extraSecretEnv:
+      - name: TRACKING_PUBLIC_TOKEN_SECRET
+        # ...
+```
+
+case-4 の Helm が前章までと違うのは、**`_helpers.tpl` による命名・ラベルの共通化**を導入している点です。Helm の慣習に沿ったチャート名・フルネーム・共通ラベルのテンプレート関数を定義し、各リソースから `{{ include "..." . }}` で呼び出します。これにより、リリース名やチャート名を含む一貫した命名・ラベル付けが自動化されます。
+
+`config.yaml` では、非機密設定を ConfigMap（`cargo-config`）に、機密値を Secret（`cargo-secret`）に展開し、`values.yaml` の `config.*` / `secret.*` から注入します。本番では `-f values-prod.yaml` や `--set` で機密値を上書きする運用が前提です（`NOTES.txt` でも警告されます）。
+
+### 検証とデプロイ
+
+```bash
+helm lint apps/case-studies/case-4-escqrs-kafka/helm/cargo-tracker
+# 1 chart(s) linted, 0 chart(s) failed
+
+helm install cargo apps/case-studies/case-4-escqrs-kafka/helm/cargo-tracker \
+  --namespace cargo-tracker --create-namespace
+```
+
+Helm 版も 11 ワークロードが `1/1 Running` になり、ゲートウェイ経由の read エンドポイントが `200` を返すことを確認しました。
+
+---
+
+## 4. ロギング基盤（EFK + DaemonSet）
+
+[第 9 章](09-container-operations.md) の **EFK（Elasticsearch + Fluentd + Kibana）+ DaemonSet** によるログ集約パターンを、本ケースにも実装として組み込んでいます（[第 13 章](13-case-monolith-compose-vs-kustomize.md) と同じ構成）。各 Pod は標準出力にログを出すだけで、各ノードに常駐する Fluentd がノード上の全 Pod のログを収集し、Elasticsearch に蓄積、Kibana で可視化します。
+
+base に `logging/` の 4 ファイルを置き、`k8s/base/kustomization.yaml` の `resources` に追加しています（local/prod 両 overlay に含まれます）。
+
+```
+logging/
+├── elasticsearch.yaml      # ConfigMap + PVC + Service + Deployment（単一ノード）
+├── fluentd-daemonset.yaml  # ServiceAccount + ClusterRole/Binding + DaemonSet
+├── kibana.yaml             # Deployment + Service（NodePort 30054）
+└── kibana-setup-job.yaml   # index pattern logstash-* を自動作成する Job
+```
+
+実装上の勘所は第 13 章と共通です。
+
+- **Fluentd**: `hostPath` で `/var/log/containers` を読み取る。containerd の CRI ログ形式に合わせて `FLUENT_CONTAINER_TAIL_PARSER_TYPE` を指定（既定の json だと不一致）。ClusterRole はケース間で衝突しないよう `fluentd-cargo-tracker` に修飾
+- **Elasticsearch**: RWO PVC のため `strategy: Recreate`、heap の 3〜4 倍（2Gi）のメモリ上限で OOM を回避
+- **Kibana**: `kibana-setup` Job が index pattern と既定ビュー（Discover）を自動設定し、開いたらすぐ使える
+
+Kafka をイベントバックボーンとする本ケースでは、各サービスのアプリログ（Fluentd → Kibana）と、トピックを流れるメッセージそのもの（Kafka UI）を併用すると、イベント駆動の挙動を多面的に観測できます。base に置いているため `overlays/local`・`overlays/prod` のどちらでもロギング基盤が含まれます。
+
+```bash
+# アプリと同時にデプロイされる（kubectl apply -k k8s/overlays/local）
+kubectl -n cargo-tracker get pods -l app.kubernetes.io/component=logging
+kubectl -n cargo-tracker exec deploy/elasticsearch -- curl -s 'http://localhost:9200/logstash-*/_count'
+# Kibana を開く（kind では NodePort が localhost に出ないため port-forward が確実）
+kubectl -n cargo-tracker port-forward svc/kibana 18081:5601   # → http://localhost:18081/
+```
+
+---
+
+## 5. 比較考察
+
+case-4 は、Kustomize・Helm の両方が「実運用を意識した成熟度」に達しています。ここまでの章の知見と合わせて、両手段の到達点を整理します。
+
+| 観点 | Kustomize（base + overlays） | Helm（_helpers + values） |
+|------|------------------------------|---------------------------|
+| 環境差分 | overlay の `patches` で base を上書き | `values-<env>.yaml` / `--set` |
+| 同型サービス | base にファイル（重複あり） | `values` のリスト + ループ |
+| 命名・ラベル共通化 | `commonLabels` 等 | `_helpers.tpl` の include |
+| 機密・設定 | `secret.yaml` / `configmap.yaml` | `config.yaml`（values 駆動） |
+| ステートフル基盤（Kafka 等） | base に StatefulSet を記述 | テンプレートに固定記述 |
+| リリース管理 | なし | リビジョン・ロールバック |
+
+**環境差分の扱い**では、両者の思想の違いが明確です。Kustomize は「base を変えずに overlay でパッチを重ねる」宣言的な差分管理、Helm は「1 つのテンプレートを values で変化させる」パラメータ駆動です。本番・ローカルで構成が大きく変わる場合は overlay の見通しが良く、値だけが変わる場合は values が簡潔です。
+
+**同型サービスの繰り返し**では、これまでの章と同じく Helm のループが有利です。一方、Kustomize は overlay により**環境ごとの差分管理**で独自の強みを持ちます。
+
+case-4 のように成熟したプロジェクトでは、**「Kustomize か Helm か」は二者択一ではなく、両方を用意して状況に応じて使い分ける**ことも珍しくありません（実際 case-4 は両方を保守しています）。GitOps で環境別に宣言的管理したいなら Kustomize の overlay、チャートとして配布・バージョン管理したいなら Helm、という使い分けが現実的です。
+
+---
+
+## まとめ
+
+- Kafka ES/CQRS 版 Cargo Tracker（Kafka + ZooKeeper + PostgreSQL〔StatefulSet〕+ 6 サービス + gateway + frontendms）を Kustomize（overlays/local）と Helm の両方でデプロイし、11 ワークロードが `1/1 Running`、ゲートウェイ経由の read エンドポイントが `200` を返すことを確認しました
+- Kustomize は base + overlay で環境差分を宣言的に管理し、Helm は `_helpers.tpl` + values でテンプレートを成熟させます
+- 成熟したプロジェクトでは両手段を併用し、GitOps（overlay）と配布（チャート）で使い分けることも現実的です
+- 第 9 章の EFK + DaemonSet を base に組み込み、local/prod 両 overlay で各サービスのログを Fluentd（DaemonSet）→ Kibana で観測できるようにしました
+- 次章では、第 13〜16 章の 4 ケースを横断し、アーキテクチャとデプロイ手段の関係を総括します
+
+---
+
+- 前の章: [第 15 章 ES/CQRS マイクロサービス（Axon）のデプロイ — Kustomize 対 Helm](15-case-escqrs-axon-kustomize-vs-helm.md)
+- 次の章: [第 17 章 ケーススタディ実装比較まとめ](17-case-comparison-summary.md)
+- シリーズ目次: [Docker/Kubernetes 実践コンテナ解説](index.md)

package/lib/assets/docs/article/getting-start-docker-kubernetes/17-case-comparison-summary.md

@@ -0,0 +1,132 @@
+# 第 17 章 ケーススタディ実装比較まとめ
+
+## はじめに
+
+第 13〜16 章では、同一ドメイン（国際貨物輸送システム = Cargo Tracker）を 4 つの異なるアーキテクチャで実装し、それぞれを Docker Compose・Kustomize・Helm でデプロイして比較しました。この章では 4 ケースを横断し、**アーキテクチャの複雑さとデプロイ手段の選択がどう関係するか**を総括します。
+
+実装はすべて [`apps/case-studies/`](https://github.com/k2works/getting-started-docker-kubernetes/tree/main/apps/case-studies) にあり、ローカル Kubernetes（Docker Desktop）で実際に動作検証しています。
+
+---
+
+## 1. 4 ケースの概観
+
+| 章 | ケース | アーキテクチャ | 構成要素 | 比較した手段 |
+|----|--------|--------------|---------|------------|
+| 13 | case-1 | モノリス | アプリ 1 + PostgreSQL | Compose 対 Kustomize |
+| 14 | case-2 | イベント駆動 MS | 8 アプリ + PostgreSQL + RabbitMQ | Kustomize 対 Helm |
+| 15 | case-3 | ES/CQRS（Axon） | 8 アプリ + PostgreSQL + Axon Server | Kustomize 対 Helm |
+| 16 | case-4 | ES/CQRS（Kafka） | 8 アプリ + PostgreSQL + Kafka + ZooKeeper | Kustomize 対 Helm |
+
+ワークロード数（Pod 種別）は、モノリスの 2 個から、マイクロサービスの 10〜11 個へと大きく増えます。
+
+| ケース | デプロイされる Pod（種別） |
+|--------|--------------------------|
+| case-1 | 2（app, postgres） |
+| case-2 | 10（gateway, 6 サービス, frontend, postgres, rabbitmq） |
+| case-3 | 10（gateway, 6 サービス, frontend, postgres, axonserver） |
+| case-4 | 11（gateway, 6 サービス, frontendms, postgres, kafka, zookeeper） |
+
+---
+
+## 2. 動作検証結果のまとめ
+
+すべてのケースで、実際にデプロイして疎通を確認しました。
+
+| ケース | 手段 | 結果 |
+|--------|------|------|
+| case-1 | Docker Compose | app + postgres healthy、`/actuator/health` UP、Flyway で 12 テーブル作成 |
+| case-1 | Kustomize | app/postgres 1/1 Running、health UP |
+| case-2 | Kustomize / Helm | 10 Pod すべて 1/1 Running、gateway 経由で全 6 サービス疎通（401）、frontend 200 |
+| case-3 | Kustomize / Helm | 10 Pod すべて 1/1 Running、Axon Server ヘルス 200、gateway 疎通、frontend 200 |
+| case-4 | Kustomize / Helm | 11 Pod すべて 1/1 Running、read エンドポイント 200、Kafka started、frontend 200 |
+
+マイクロサービスの 3 ケース（case-2/3/4）は、Kustomize と Helm の**両方**で同一システムをデプロイし、同じ疎通結果が得られることを確認しています。
+
+---
+
+## 3. デプロイ手段の比較軸まとめ
+
+### Docker Compose 対 Kustomize（第 13 章の知見）
+
+| 観点 | Docker Compose | Kustomize |
+|------|----------------|-----------|
+| 対象 | 単一ホスト | Kubernetes クラスタ |
+| 機密 | 環境変数 / `.env` | Secret |
+| 永続化 | named volume | PVC |
+| 公開 | ポート公開 | Service + Ingress |
+| 自己修復・スケール | 限定的 | Deployment が標準提供 |
+
+Compose は「ローカルで素早く全体を起動する」用途に最適で、Kustomize（Kubernetes）は「本番でスケール・自己修復・公開を宣言的に管理する」用途に向きます。
+
+### Kustomize 対 Helm（第 14〜16 章の知見）
+
+| 観点 | Kustomize | Helm |
+|------|-----------|------|
+| 同型サービスの繰り返し | サービスごとにファイル | `values` のリスト + ループ |
+| サービスの性質差（DB/Axon/JWT） | env を書く / 書かない | フラグ + `{{- if }}` |
+| 環境差分 | base + overlay の `patches` | `values-<env>.yaml` / `--set` |
+| 命名・ラベル共通化 | `commonLabels` | `_helpers.tpl` |
+| 単発インフラ（Kafka/Axon Server） | 専用ファイル | テンプレートに固定記述 |
+| リリース管理 | なし（kubectl apply） | リビジョン・ロールバック |
+| 透明性 | 生 YAML に近い | `helm template` で展開して確認 |
+
+---
+
+## 4. 横断的な考察 — 複雑さとデプロイ手段
+
+4 ケースを並べると、一貫した傾向が見えます。
+
+### (1) 構成要素が増えるほどテンプレート化（Helm）の価値が高まる
+
+モノリス（case-1）では、デプロイ対象が少なく、Compose の簡潔さと Kustomize の明示性のどちらも十分でした。手段の差は「好みと運用要件」の範囲です。
+
+マイクロサービス（case-2/3/4）になると、6〜7 個の**同型サービス**が現れます。Kustomize ではこれを個別ファイルに書き下すため重複が増え、Helm では `values` のリスト + ループ 1 つに集約できます。**同型コンポーネントが多いほど、Helm のテンプレート化が記述量と保守性で有利**になります。
+
+### (2) サービスの「性質の差」はデータとして表現できる
+
+case-3 では「Axon を使う / 使わない」「JWT を持つ / 持たない」、case-4 では「追加 Secret 環境変数の有無」といったサービスごとの差がありました。Kustomize はファイルの書き分けで、Helm は `axon: true` のようなフラグ + 条件分岐で表現します。**性質をデータ化してテンプレートに構造を生成させる**Helm のアプローチは、サービスが増えるほど効きます。
+
+### (3) 単発の「特別なインフラ」では差が縮まる
+
+Axon Server（case-3）や Kafka + ZooKeeper（case-4）のような単発のステートフル基盤は、ループの恩恵がないため、Kustomize と Helm で記述量はほぼ同じです。繊細で固有な設定（Axon の standalone/DCB、Kafka のリスナー設定など）は、生 YAML に近い Kustomize のほうが意図を追いやすいという見方もできます。
+
+### (4) 環境差分は overlay（Kustomize）と values（Helm）で思想が異なる
+
+case-4 で見たように、Kustomize は「base を変えずに overlay でパッチを重ねる」、Helm は「1 つのテンプレートを values で変化させる」という異なる思想で環境差分を扱います。構成自体が環境で変わるなら overlay、値だけが変わるなら values が簡潔です。
+
+### (5) 二者択一とは限らない
+
+case-4 は Kustomize と Helm の**両方**を保守していました。GitOps で環境別に宣言的管理したいなら Kustomize の overlay、チャートとしてバージョン管理・配布したいなら Helm、と**併用して使い分ける**のも現実的な選択です。
+
+---
+
+## 5. 選択の指針
+
+これまでの検証を踏まえた、実務的な選択の目安です。
+
+| 状況 | 推奨 |
+|------|------|
+| ローカル開発で全体を素早く起動したい | Docker Compose |
+| 少数のコンポーネントを Kubernetes へ | Kustomize（base のみ） |
+| 同型サービスが多いマイクロサービス | Helm（ループ + フラグ） |
+| 環境ごとに構成が変わる | Kustomize（overlay）または併用 |
+| チャートとして配布・バージョン管理したい | Helm |
+| GitOps で宣言的に環境別管理 | Kustomize の overlay（+ Helm 併用も可） |
+
+アーキテクチャが複雑になるほど、デプロイ手段は「動けばよい」から「重複を抑え、環境差分を安全に管理し、リリースを追跡できる」ことが重要になります。本ケーススタディは、その移行を 1 つのドメインの 4 実装で具体的に示しました。
+
+---
+
+## まとめ
+
+- 同一ドメインの 4 アーキテクチャ（モノリス / イベント駆動 / ES・CQRS Axon / ES・CQRS Kafka）を、Compose・Kustomize・Helm で実装・デプロイ・検証しました
+- 構成要素が増えるほど、同型サービスのテンプレート化（Helm）と環境差分の宣言的管理（Kustomize overlay）の価値が高まります
+- 単発インフラでは両手段の差は縮まり、繊細な設定はむしろ Kustomize の透明性が活きます
+- 「Kustomize か Helm か」は二者択一ではなく、GitOps と配布で併用する選択も現実的です
+- これでシリーズ全体（基礎 12 章 + ケーススタディ 5 章 + 付録 3）を通じ、コンテナの基礎から実システムのデプロイ手段の選択までを一貫して学べます
+
+---
+
+- 前の章: [第 16 章 ES/CQRS マイクロサービス（Kafka）のデプロイ — Kustomize 対 Helm](16-case-escqrs-kafka-kustomize-vs-helm.md)
+- 次の章: [第 18 章 ケーススタディの負荷テスト](18-case-load-testing.md)
+- シリーズ目次: [Docker/Kubernetes 実践コンテナ解説](index.md)