設計に疎いエンジニアでも始めやすいアーキテクチャドキュメント

Kome Kaigi 2025 で登壇させていただいた際の資料です。
https://komekaigi.dev/

Transcript

1. 設計に疎いエンジニアでも始めやすい アーキテクチャドキュメント Kome Kaigi 2025 - Tomonori Hayashi / ぴーはや
2. 2 Agenda 18:00 - Opening 18:03 - Keynote 「Google Cloud Next ‘25 Wrap Up !!」 Google Cloud Japan Mori-san, Nakane-san Shigeru-san 18:45 - Community Member LT-1「振り返りと気になったセッション」 DocoTech Kanzaki-san 18:55 - Guest LT-1「A2A のドキュメントソースコードを読んでみた」 DII Yamazaki-san 19:05 - Guest LT-2「GKEラウンドテーブルと気になったセッションの振り返り」 Docomo Toe-san 19:15 - Community Member LT-2「ワークロードの規模でみる Cloud Run のアーキテクチャ」 Com Hayashi-san 19:30 - Community Member LT-3「振り返りと気になったセッション」 Docomo Fujihira-san, Yano-san 19:45 - Closing Tomonori Hayashi / ぴーはや • NTTドコモビジネス株式会社 ◦ ソフトウェアエンジニア ノーコード AI 開発ツール「Node-AI」の開発/運用 ▪ Front：TypeScript - React/Next.js ▪ Infra：Google Cloud • Google Cloud Partner Top Engineer 2024 - 2025 • Google Cloud All Certifications • コミュニティ ◦ Jagu’e’r（Google Cloud ユーザーコミュニティ） ▪ エバンジェリスト • カンファレンス ◦ SRE Kaigi 2026（2026.01.31 開催） ▪ コアスタッフ 2 @pHaya72 @srekaigi
3. 3 アーキテクチャドキュメントって重要ですよね？ 3
4. 4 本日お話しすること GKE から Cloud Run への移行検証をきっかけに直面した 設計の属人化に対して アーキテクチャドキュメントの活用によって乗り越えた話 4
5. 5 本日お話しすること 5 Google Cloud での インフラリビルドの経緯やつまずき 設計に詳しくないエンジニアでも 始めやすいアーキテクチャドキュメント
6. © NTT Communications Corporation All Rights Reserved. 6 Node-AI の紹介 時系列分析に特化した ノーコード AI 開発 Web アプリケーション Asyc Processing GKE ☑ 開発者数名で内製開発 しているプロダクト
 
 ☑ アジャイル開発で 1 週間での機能リリース
 
 ☑ アプリケーションはマイクロサービスとして 
 　 GKE でホスティングして運用 
 ブラウザからすぐに無料で 始めることができます！ 6
7. © NTT Communications Corporation All Rights Reserved. 7 直面した設計の属人化 Asyc Processing GKE GKE で運用する上での難しさ ・ノードプールの適切な設計と管理 ・スケーリングの繊細なチューニング ・ミドルウェアとの魔合体 ・社内 DevOps ツールとの強い依存 … etc インフラ 
 任せろ！！ 
 インフラ 
 わからん！！ 
 インフラ 
 無理！！ 
 インフラ 
 任せた！！ 
 インフラ 
 なにそれ！！ 
 インフラ 
 うおおお！！ 
 ※ イメージです 7 GKE（Kubernetes + Google Cloud）という 学習コストの高さも相まって属人化が加速 少人数の開発者チームの中でも 特定のメンバーのみが GKE 職人となる
8. © NTT Communications Corporation All Rights Reserved. 8 初めてのインフラリビルドを決断 GKE（Kubernetes + Google Cloud）という 学習コストの高さも相まって属人化が加速 GKE で運用する上での難しさ ・ノードプールの適切な設計と管理 ・コントロールプレーンやノードのコスト管理 ・スケーリングの繊細なチューニング ・社内 DevOps ツールとの強い依存 … etc 少人数の開発者チームの中でも 特定のメンバーのみが GKE 職人となる 属人化解消として初めてインフラリビルドに挑戦！ フルマネージドサービスである Cloud Run を検討対象に Asyc Processing Asyc Processing GKE GKE Cloud Run Worker Pools 8
9. © NTT Communications Corporation All Rights Reserved. 9 Cloud Run とは？ HTTP リクエスト・イベントベースのアプリケーションのホスティングなどに 最適なゼロスケールをする Google Cloud のコンテナプラットフォーム Services HTTP リクエスト受けて動作する、ステートレスなコンテナを実行するためのサービス ユースケース：Web サービス、API、マイクロサービス Jobs 一定の有限時間の処理を実行して終了するコンテナを実行するためのサービス ユースケース：バッチ処理、データ変換、機械学習モデルの学習や推論 Functions イベントに応じて、単一の小さなコード = 関数を実行するためのサービス ユースケース：ファイルアップロード時の処理、 IoTデバイスからのメッセージ処理 9
10. © NTT Communications Corporation All Rights Reserved. 10 Cloud Run とは？ HTTP リクエスト・イベントベースのアプリケーションのホスティングなどに 最適なゼロスケールをする Google Cloud のコンテナプラットフォーム Services HTTP リクエスト受けて動作する、ステートレスなコンテナを実行するためのサービス ユースケース：Web サービス、API、マイクロサービス Jobs 一定の有限時間の処理を実行して終了するコンテナを実行するためのサービス ユースケース：バッチ処理、データ変換、機械学習モデルの学習や推論 Functions イベントに応じて、単一の小さなコード = 関数を実行するためのサービス ユースケース：ファイルアップロード時の処理、 IoTデバイスからのメッセージ処理 10 Worker Pools 今年 4 月に発表された Cloud Run の新しい実行モデル HTTP エンドポイントは不要 常駐稼働型アプリケーションに最適 ユースケース： Pub/Sub サブスクライバー、 Kafka コンシューマ処理 Preview このモデルの登場により Cloud Run が 
 カバーできるユースケースがさらに拡大
 Point !!
11. © NTT Communications Corporation All Rights Reserved. 11 Cloud Run とは？ HTTP リクエスト・イベントベースのアプリケーションのホスティングなどに 最適なゼロスケールをする Google Cloud のコンテナプラットフォーム Services HTTP リクエスト受けて動作する、ステートレスなコンテナを実行するためのサービス ユースケース：Web サービス、API、マイクロサービス Jobs 一定の有限時間の処理を実行して終了するコンテナを実行するためのサービス ユースケース：バッチ処理、データ変換、機械学習モデルの学習や推論 Functions イベントに応じて、単一の小さなコード = 関数を実行するためのサービス ユースケース：ファイルアップロード時の処理、 IoTデバイスからのメッセージ処理 11 Worker Pools 今年 4 月に発表された Cloud Run の新しい実行モデル HTTP エンドポイントは不要 常駐稼働型アプリケーションに最適 ユースケース： Pub/Sub サブスクライバー、 Kafka コンシューマ処理 Preview 移行検証はミニマム始めたかったため、システムへの影響度をコントロールしやすい 機械学習処理を担う非同期処理のワーカーコンポーネントを対象に検証！
12. © NTT Communications Corporation All Rights Reserved. 12 初のインフラリビルド順調かと思いきや・・・ Asyc Processing Asyc Processing GKE GKE Cloud Run Worker Pools 既存の挙動を再現するようにマイグレーション 移行検証はつまづきも多少あったが、問題なく完了したと 思われたが、、 GKE 職人にレビューしてもらうと多くの指摘が入った 「この構成はセキュリティ面を考慮する必要がある」 「処理中にアップデートがかかっても大丈夫？」 「ここは権限を極力絞っておきたい」 「・・・結構、考慮漏れしている・・・」 GKE 職人 私 12 GKE
13. 13 確認可能な機能面 = システムの振る舞い だけに意識が行ってしまっていて システムがどのように振る舞うか = アーキテクチャ特性 の考慮が欠如していた 13
14. © NTT Communications Corporation All Rights Reserved. 14 アーキテクチャ特性とは？ ‘‘ アーキテクチャ特性とは、次の 3 つの基準を満たすものだ。 • ドメインに依らない、設計に関する考慮事項を明らかにするもの • 設計の構造的な側面に影響を与えるもの • アプリケーションの成功に不可欠か重要なもの ’’ — 4章 アーキテクチャ特性 ‘‘ システムがサポートしなければいけない「イリティ（ -ility）」を指す ’’ Ex. 可用性（Availability）, スケーラビリティ（Scalability）, セキュリティ（Security） — 1章 イントロダクション 14
15. © NTT Communications Corporation All Rights Reserved. 15 始めやすいアーキテクチャドキュメント なぜアーキテクチャ特性が欠如してしまったのか？ 特定のメンバーの頭にしか設計がない = 設計の属人化 によって機能面だけを満たすように検証を始めてしまった 私 「やっぱドキュメントは必要か」 「しかし、なにを書けばいいのか・・」 15 今回書いてみて始めやすく共通認識を構築するのに役立ったアーキテクチャドキュメントを紹介 （ここでのアーキテクチャドキュメントは、UML 図(※1) や C4 モデル(※2) を参考にした設計に関わるドキュメント群という緩めの定義 とします）
16. © NTT Communications Corporation All Rights Reserved. 16 なぜアーキテクチャ特性が欠如してしまったのか？ 特定のメンバーの頭にしか設計がない = 設計の属人化 によって機能面だけを満たすように検証を始めてしまった 私 「やっぱドキュメントは必要か」 「しかし、なにを書けばいいのか・・」 システムアーキテクチャとコンポーネントアーキテクチャを定義 システムアーキテクチャ（ソフトウェア） 
 コンポーネントアーキテクチャ（構成要素） 
 機能要件 非機能要件 今回対象としたのはシステムの 1 つの構成要素
 なのでコンポーネントアーキテクチャを考える 
 16 Point !! ※ 以降の記載内容は実際のもの ではなくサンプルです 始めやすいアーキテクチャドキュメント 今回書いてみて始めやすく共通認識を構築するのに役立ったアーキテクチャドキュメントを紹介 （ここでのアーキテクチャドキュメントは、UML 図(※1) や C4 モデル(※2) を参考にした設計に関わるドキュメント群という緩めの定義 とします）
17. © NTT Communications Corporation All Rights Reserved. 17 システムコンテキスト図 (※3) まずは注目しているコンポーネントが周辺のコンポーネントとどのようなやりとりをしているかを書き出すことで、 シ ステムの境界線を明確に定義 する 開発対象のシステム /コンポーネントとその外部環境との相互作用を可視化 開発対象の コンポーネント （ML Component） タスクを キューに格納 処理対象のファイルを ストレージから取り出す テレメトリを送信 Object Storage Telemetry Storage Backend Component Task Queue タスクを取得 17 タスクのステータス取得 Database
18. © NTT Communications Corporation All Rights Reserved. 18 コンテナ図 (※4) 次に注目しているコンポーネントを一段階クローズアップ しつつ、周辺の構成されているコンテナ同士の連携 や内部の関係性 を明らかにする 開発対象のシステム /コンポーネントがどのようなコンテナで構成されているかを可視化 ML Component 機械学習の 非同期処理ワーカー オブザーバビリティ エージェント Cloud Storage Cloud Observability Memorystore for Redis ① タスクを取得 テレメトリを 送信 ③ 処理対象 ファイルを取得 ④ 機械学習処理 ⑥ 処理後の ファイルを格納 ⑥ タスクを格納 18 Cloud SQL ② タスクの ステータス更新 ⑤ タスクの ステータス更新 テレメトリを送信
19. © NTT Communications Corporation All Rights Reserved. 19 コンテナ図 (※4) 次に注目しているコンポーネントを一段階クローズアップ しつつ、周辺の構成されているコンテナ同士の連携 や内部の関係性 を明らかにする 開発対象のシステム /コンポーネントがどのようなコンテナで構成されているかを可視化 ML Component 機械学習の 非同期処理ワーカー オブザーバビリティ エージェント Cloud Storage Cloud Observability Memorystore for Redis ① タスクを取得 テレメトリを 送信 ③ 処理対象 ファイルを取得 ④ 機械学習処理 ⑥ 処理後の ファイルを格納 ⑥ タスクを格納 19 Cloud SQL ② タスクの ステータス更新 ⑤ タスクの ステータス更新 テレメトリを送信 連携がどのような手順で
 何をしているかも記載していく
 Point !!
20. © NTT Communications Corporation All Rights Reserved. 20 デプロイメント図 (※4) 今回はインフラの移行検証のため 実行環境の配置を可視化 するデプロイメント図を採用した、これにより インフ ラの性質を考慮しつつアーキテクチャ特性も整理 する 開発対象のシステム /コンポーネントがどのような実行環境に配置されているかを可視化 Cloud Run worker pools ML Component 機械学習の非同期処理ワーカー オブザーバビリティ エージェント Cloud SQL Cloud Storage ③ 処理対象 ファイルを取得 Memory Store for Redis ④ 機械学習処理 ⑤ タスクの ステータス更新 ⑥ 処理後の ファイルを格納 ① タスクを取得 ⑥ タスクを格納 ② タスクの ステータス更新 テレメトリを 送信 20 Ex. 負荷の量に応じて対応可能 運用負荷を減らしたいため → 擬似オートスケーラーの実装が必要 スケーラビリティ Ex. 処理空間の分離可能 他データへのアクセス防ぐため → 1 ワーカーあたり 1 プロセスを起動 セキュリティ Ex. 新バージョンへのアップグレードが簡単に可能 処理中のタスクを安全に完了するため → 途中終了時はタスクを再キューイング アップグレード容易性 Cloud Logging Cloud Trace
21. © NTT Communications Corporation All Rights Reserved. 21 デプロイメント図 (※4) 今回はインフラの移行検証のため 実行環境の配置を可視化 するデプロイメント図を採用した、これにより インフ ラの性質を考慮しつつアーキテクチャ特性も整理 する 開発対象のシステム /コンポーネントがどのような実行環境に配置されているかを可視化 Cloud Run worker pools ML Component 機械学習の非同期処理ワーカー オブザーバビリティ エージェント Cloud SQL Cloud Storage ③ 処理対象 ファイルを取得 Memory Store for Redis ④ 機械学習処理 ⑤ タスクの ステータス更新 ⑥ 処理後の ファイルを格納 ① タスクを取得 ⑥ タスクを格納 ② タスクの ステータス更新 テレメトリを 送信 21 Ex. 負荷の量に応じて対応可能 運用負荷を減らしたいため → 擬似オートスケーラーの実装が必要 スケーラビリティ Ex. 処理空間の分離可能 他データへのアクセス防ぐため → 1 ワーカーあたり 1 プロセスを起動 セキュリティ Ex. 新バージョンへのアップグレードが簡単に可能 処理中のタスクを安全に完了するため → 途中終了時はタスクを再キューイングx アップグレード容易性 Cloud Logging Cloud Trace アーキテクチャ特性で何を実現したいのか
 なぜ必要なのかなどを記載していく
 Point !!
22. © NTT Communications Corporation All Rights Reserved. 22 今回役立ったアーキテクチャドキュメント 注目しているシステム /コンポーネントを徐々にクローズアップ していき、会話しているだけでは抜け落ちそう な考慮事項、特にアーキテクチャ特性と必要な理由をドキュメント化して議論 する システムコンテキスト図 外部環境との相互作用を可視化 コンテナ図 構成されているコンテナ間の関係を可視化 デプロイメント図 コンテナの実行環境の配置を可視化 コンポーネント図 コンポーネント間の論理的な関係を可視化 22 重厚長大にならない程度から始める！
 Point !!
23. © NTT Communications Corporation All Rights Reserved. 23 今回役立ったアーキテクチャドキュメント 注目しているシステム /コンポーネントを徐々にクローズアップ していき、会話しているだけでは抜け落ちそう な考慮事項、特にアーキテクチャ特性と必要な理由をドキュメント化して議論 する システムコンテキスト図 このようなドキュメントの積み重ねがアーキテクチャにおける重要な決定事項 = アーキテクチャ決定（ Architecture Decision）を残すことにつながる 時が経ったときのリファクタリングなどの変更をしたい時に 
 考慮漏れを防ぎ安全に取り組むことが可能に 
 外部環境との相互作用を可視化 コンテナ図 構成されているコンテナ間の関係を可視化 デプロイメント図 コンテナの実行環境の配置を可視化 コンポーネント図 コンポーネント間の論理的な関係を可視化 23 重厚長大にならない程度から始める！
 Point !! Point !!
24. 24 Agenda 18:00 - Opening 18:03 - Keynote 「Google Cloud Next ‘25 Wrap Up !!」 Google Cloud Japan Mori-san, Nakane-san Shigeru-san 18:45 - Community Member LT-1「振り返りと気になったセッション」 DocoTech Kanzaki-san 18:55 - Guest LT-1「A2A のドキュメントソースコードを読んでみた」 DII Yamazaki-san 19:05 - Guest LT-2「GKEラウンドテーブルと気になったセッションの振り返り」 Docomo Toe-san 19:15 - Community Member LT-2「ワークロードの規模でみる Cloud Run のアーキテクチャ」 Com Hayashi-san 19:30 - Community Member LT-3「振り返りと気になったセッション」 Docomo Fujihira-san, Yano-san 19:45 - Closing まとめ GKE から Cloud Run に移行検証する中で 設計の属人化に直面してアーキテクチャドキュメントの重要性を実感 （検証は継続中、結果は来年の Kome Kaigi で！） • 「システムの振る舞い」だけでなく「システムがどのように振る舞うか = アーキテクチャ特性」にも十分に意 識を向ける必要がある • とは言え、ドキュメントは腐りやすいなど作った後のメンテナンスは課題 アーキテクチャにおける重要な決定事項 = アーキテクチャ決定（ Architecture Decision）は このような形で残して、共通認識のすり合わせやアーキテクチャ変更に活用！！ 24
25. 25 Agenda 18:00 - Opening 18:03 - Keynote 「Google Cloud Next ‘25 Wrap Up !!」 Google Cloud Japan Mori-san, Nakane-san Shigeru-san 18:45 - Community Member LT-1「振り返りと気になったセッション」 DocoTech Kanzaki-san 18:55 - Guest LT-1「A2A のドキュメントソースコードを読んでみた」 DII Yamazaki-san 19:05 - Guest LT-2「GKEラウンドテーブルと気になったセッションの振り返り」 Docomo Toe-san 19:15 - Community Member LT-2「ワークロードの規模でみる Cloud Run のアーキテクチャ」 Com Hayashi-san 19:30 - Community Member LT-3「振り返りと気になったセッション」 Docomo Fujihira-san, Yano-san 19:45 - Closing Thanks! @pHaya72 @t_hayashi 25
26. 26 Agenda 18:00 - Opening 18:03 - Keynote 「Google Cloud Next ‘25 Wrap Up !!」 Google Cloud Japan Mori-san, Nakane-san Shigeru-san 18:45 - Community Member LT-1「振り返りと気になったセッション」 DocoTech Kanzaki-san 18:55 - Guest LT-1「A2A のドキュメントソースコードを読んでみた」 DII Yamazaki-san 19:05 - Guest LT-2「GKEラウンドテーブルと気になったセッションの振り返り」 Docomo Toe-san 19:15 - Community Member LT-2「ワークロードの規模でみる Cloud Run のアーキテクチャ」 Com Hayashi-san 19:30 - Community Member LT-3「振り返りと気になったセッション」 Docomo Fujihira-san, Yano-san 19:45 - Closing 出典 & 参考 出典 • ※1 Unified Modeling Language（統一モデリング言語） ◦ https://ja.wikipedia.org/wiki/%E7%B5%B1%E4%B8%80%E3%83%A2%E3%83%87%E3%83%AA%E3%83 %B3%E3%82%B0%E8%A8%80%E8%AA%9E • ※2 C4 モデル ◦ https://c4model.com/ • ※3 システムコンテキスト図 ◦ https://c4model.com/diagrams/system-context • ※4 コンテナ図 ◦ https://c4model.com/diagrams/container • ※5 デプロイメント図 ◦ https://c4model.com/diagrams/deployment ◦ https://ja.wikipedia.org/wiki/%E9%85%8D%E7%BD%AE%E5%9B%B3 参考 • C4モデル ◦ https://zenn.dev/nac/articles/n33467_c4model 26