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

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

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

次のステップ