アーキテクチャ決定レコードの概要

インフラストラクチャまたはアプリケーション チームが特定の設計上の選択を行う理由を説明するために、アーキテクチャ決定レコード(ADR)を使用できます。このドキュメントでは、Google Cloud でアプリケーションをビルドして実行する際に ADR を使用するタイミングと方法について説明します。

ADR は、使用可能な主要なオプション、決定を推進する主な要件、設計上の決定事項をキャプチャします。ADR は、その決定に関連するコードベースの近くの Markdown ファイルに保存することがよくあります。リージョンの Google Kubernetes Engine(GKE)クラスタを使用する理由など、特定のアーキテクチャ決定の背景を理解する必要がある場合は、ADR を参照して関連するコードを確認できます。

ADR は、信頼性の高いアプリケーションとサービスの実行にも役立ちます。ADR は、現在の状況の把握と問題が発生した場合のトラブルシューティングに役立ちます。 また、ADR は、将来の意思決定の選択とデプロイに役立つ一連のエンジニアリング上の決定とデプロイも作成します。

ADR を使用する場面

ADR を使用して、デプロイで重要と考えられる領域を追跡します。ADR には次のカテゴリが考えられます。

  • 具体的なプロダクトの選択(Pub/Sub と Pub/Sub Lite の選択など)。
  • 特定のプロダクト オプションと構成(高可用性アプリケーション用のマルチクラスタ Ingress でリージョン GKE クラスタを使用するなど)。
  • Dockerfile マニフェストのベスト プラクティスなど、アーキテクチャに関する一般的なガイダンス。

ADR の作成を求める可能性のある具体的な例は、次の選択肢のいずれかです。

ADR は、使用するプロダクトを評価するときに、各決定を説明するのに役立ちます。Pub/Sub と Pub/Sub Lite のどちらを選ぶかを示す例では、使用するプロダクトの決定に要件がいかに役立つかについて、ADR で説明する場合があります。次の表に、Pub/Sub と Pub/Sub Lite の違いをいくつか示します。

機能 Pub/Sub Pub/Sub Lite
メッセージ レプリケーション シングル リージョン内のマルチゾーン シングルゾーン
容量 自動プロビジョニング済み 使用前にプロビジョニング
料金 使用した容量に対しての支払い プロビジョニングした容量に対しての支払い
保存 無制限 Lite トピックあたり 30 GiB~10 TiB
保持期間 最大 7 日 無制限
Service エンドポイント グローバルとリージョナル リージョン
リソースの名前空間 グローバル ゾーン
メッセージ ルーティング グローバル ゾーン

要件には、単一リージョン内の複数のゾーンにわたるグローバル メッセージ ルーティングやメッセージ レプリケーションが含まれる場合があります。この例では、これらの機能によって Pub/Sub を使用していることを説明する ADR がありますが、Pub/Sub Lite はゾーン メッセージ ルーティングとシングルゾーン メッセージ レプリケーションのみが提供されます。

チームが進化してスタックについてさらに学習し、追加の意思決定や調整を行う際には、ADR を再検討できます。調整を行う場合は、変更の内容と変更を行った理由を含めます。この履歴には、ビジネスニーズの変化に応じてアーキテクチャがどのように変更されたか、新しい技術要件や利用可能なソリューションがある場所が記録されます。

次のプロンプトは、ADR を作成するタイミングの判断に役立ちます。

  • 技術的課題や技術的問題があり、推奨ソリューション、標準運用手順、ブループリント、コードベースなどの意思決定の根拠がない場合。
  • 自分またはチームが、チームがアクセスできる場所に記載されていないソリューションを提供した場合。
  • 複数のエンジニアリング オプションがあり、選択の背後にある思考と理由を文書化する場合。

ADR を作成する際は、読者を念頭に置いておくことをおすすめします。主な読者は、ADR の対象となる技術に携わるチームメンバーです。ADR の読者となる可能性のあるユーザー層としては、アーキテクチャやセキュリティ チームなど、意思決定を理解したいと考えている隣接チームが含まれることもあります。

また、アプリケーションによってオーナーが変更されることや、新しいチームメンバーが含まれる可能性があることも考慮する必要があります。ADR は、新しいエンジニアが、選択したエンジニアリングの背景を理解するのに役立ちます。ADR では、将来の変更を簡単に計画できます。

ADR の形式

一般的な ADR には複数の章が含まれています。ADR は、アプリケーションと組織にとって重要と思われるものをキャプチャするのに役立ちます。ADR には 1 ページのものもあれば、長い説明が必要なものもあります。

次の ADR 概要の例は、お客様の環境で重要な情報を含む ADR をどのようにフォーマットするかを示しています。

  • 作成者とチーム
  • 解決するコンテキストと問題
  • 対応したい機能面と機能面以外の要件
  • 意思決定が影響する可能性があるクリティカル ユーザー ジャーニー(CUJ)
  • 主なオプションの概要
  • お客様の判断とその理由

決定を記録するために、選択が行われた日時を示す各決定のタイムスタンプを含めることができます。

ADR の仕組み

エンジニア、デベロッパー、アプリケーション オーナーが、ADR に含まれる情報に簡単にアクセスできる際に、ADR は最も効果的に機能します。なんらかの方法で特定の処理が行われた理由について質問がある場合は、ADR を調べてその答えを見つけることができます。

ADR にアクセスできるようにするために、一部のチームはソース管理リポジトリではなく、ビジネス オーナーもアクセスできる中央の Wiki で ADR をホストしています。特定のエンジニアリング上の決定に関して疑問が生じた場合に ADR が回答を提供します。

ADR は次のような場合に適しています。

  • オンボーディング: 新しいチームメンバーはプロジェクトを簡単に把握でき、アプリケーション コードやその他の実装の確認時に疑問がある場合には ADR を確認できます。
  • 所有権の引き継ぎ: チーム間での技術スタックの移行がある場合、新しいオーナーは過去の決定事項を確認して、現状を把握できます。ADR は、同じ論点が繰り返されるのを回避したり、履歴コンテキストに関する知識を使用して今後トピックを再検討したりするのに役立ちます。
  • アライメント: チームは、ADR が特定の決定を行い、別の案が却下された理由の詳細について、組織全体のベスト プラクティスに配置することができます。

ADR は通常、軽量でテキストベースの Markdown で記述されます。Markdown ファイルは、アプリケーション コードと一緒にソース管理リポジトリに含めることができます。

ADR はアプリケーション コードの近くに、理想的には同じバージョン管理システムに保存します。ADR に変更を加える際に、必要に応じてソース管理の以前のバージョンを確認できます。

共有 Google ドキュメントや内部 Wiki など、別のメディアを使用することもできます。 これらの代替の場所は、ADR のチームメンバーではないユーザーがよりアクセスしやすい場合があります。もう 1 つの方法は、ソース管理リポジトリで ADR を作成し、重要な決定をよりアクセスしやすい Wiki にミラーリングすることです。

次のステップ