dbt Docs をホスティングする AWS インフラ構成

こんにちは！シンプルフォームの山岸です。

皆さん、データ基盤のメタデータ管理には何を利用されているでしょうか。
当社では現在、Snowflake × dbt を軸としたデータ基盤への移行に向けて検証・構築を進めており、併せて dbt Docs の機能を用いたメタデータ管理・提供方法についても検討しています。

今回、dbt Docs を AWS 上で CI/CD、およびホスティングするための AWS インフラ構成について検討してみたので、本記事ではその内容についてご紹介できればと思います。（アーキテクチャの話がメインであり、細かい実装についてはあまり言及しない点について、予めご了承ください）

メタデータ管理について

メタデータとは

データ基盤の文脈における「メタデータ」とは、一言で言えば「データに関するデータ」のことを指します。これには例えば、DB 内の各テーブル・カラムのビジネス的意味や、データの物理的な所在・保存方法、アクセス権限、運用上付与されているタグ などが該当します。

データマネジメントにおいてメタデータ管理は非常に重要であり、DMBOK ^[1] 知識領域の一つにもなっています。メタデータを適切に管理・提供することで、データ利用者のデータに対する理解を促進し、ステークホルダー間（開発者、データエンジニア、データ利用者 等）のコミュニケーションコストを大幅に抑えることができます。

データカタログ

メタデータを管理・提供するシステムを、一般に「データカタログ」と言います。

https://blog.trocco.io/glossary/data-catalog

dbt Docs

本記事でご紹介する dbt Docs は、dbt が提供するデータカタログ機能です。
dbt プロジェクト内のモデル定義や、そのモデルに対応する実際のテーブル情報に基づいて、メタデータを生成・ホスティングするための機能を提供します。（OSS 版の dbt Core でも利用可能）

出典: Auto-generated documentation for a dbt model ^[2]

オプションの説明などは割愛しますが、主に使用するコマンドは以下の通りです。^[3]

% dbt docs generate  # ドキュメントファイル群の生成
% dbt docs serve     # Web サーバーの起動

その他のデータカタログ製品・サービス

dbt Docs 以外のデータカタログ製品・サービスとして、Open Metadata や primeNumber 社が提供する COMETA といったものがあります。これらはより統合的なメタデータ基盤を提供し、データの発見やガバナンス向上を支援します。

また、各パブリッククラウドベンダーも類似のサービスを提供しています。

パブリッククラウド	該当するサービス
AWS	AWS Glue Data Catalog ／ Amazon DataZone
Google Cloud	Dataplex
Microsoft Azure	Data Catalog

dbt Docs をどこでホスティングするか

dbt Docs で生成したメタデータドキュメントは、ローカルサーバーを起動することでも内容を確認できますが、データ利用者に提供する際はどこかにホスティングする必要があります。

dbt プロジェクトのソースコードを GitHub で管理している場合、GitHub Actions で最新のドキュメントファイルを生成し、プライベートな GitHub Pages として社内公開することが可能です。

• データ基盤における管理の考え方 〜dbtの極意〜：LayerXにdbtを導入するときに意識したこと (Slide#18) - SpeakerDeck
• Private GitHub Pagesで社内ドキュメントを公開しよう！ - メドピア開発者ブログ

しかし、GitHub アカウントを持っていないデータ利用者メンバーが多い場合、GitHub Pages にホスティングするのが難しいケースもあるかと思います。そこで本記事では、CI/CD を AWS CodePipeline で、ホスティングを Amazon CloudFront + S3 で構成する方法についてご紹介できればと思います。

前置きが長くなりましたが、以降にそのインフラ構成について説明していきます。

AWS インフラ構成

インフラ構成の全体像は以下の通りです。

• dbt プロジェクトのソースコードは組織の GitHub リポジトリで管理されています。
• GitHub Actions ワークフローから dbt Docs 用の CI/CD パイプライン (CodePipeline) を実行します。パイプラインから呼び出される CodeBuild プロジェクトで dbt Docs を生成し、所定の S3 パスにそのアーティファクトを出力します。
• S3 バケットをオリジンとする CloudFront ディストリビューションを構築し、その URL を Route 53 エイリアスレコードとして登録します。許可されたメンバーのみがアクセスできるよう、SAML 認証用の Lambda 関数をビヘイビアとして設定します。

CI/CD とホスティングのそれぞれについて、以下にもう少し詳細に説明したいと思います。

CI/CD

以下の図は、CI/CD 部分のうち GitHub リポジトリ → S3 バケットの部分を詳細化したものです。

CodePipeline

当社では Snowflake スキーマ毎に dbt プロジェクトを作成しており、dbt Docs もプロジェクトの数だけ生成されることになります。プロジェクト毎に専用の CodePipeline を用意し、product1 プロジェクトであれば、出力先 S3 バケットには projects/product1 にアーティファクトを出力するよう構成しています。

CodeBuild プロジェクト

CodePipeline はプロジェクト毎に作成していますが、CodeBuild プロジェクトは環境変数 PROJECT_NAME を指定して、複数の CodePipeline から使い回せるよう共通化しています。

AWS 管理の Linux ランタイムを使用し、dbt docs generate コマンドの実行に必要なパッケージ群をビルド毎にインストールしても良いですが、事前インストール済みの ECR イメージを指定することで毎回のインストール処理を省略することができます。

キャッシュ無効化用 Lambda 関数

オリジン用バケットの中身が更新されても、エッジロケーションのキャッシュが残っている限り、ユーザーは古いドキュメントを参照することになります。CI/CD パイプライン実行後に最新のものを参照できるようにするには、以下の記事で説明されているようなキャッシュ無効化の Action を CodePipeline の後段に設定しておきます。

• CodePipelineからAWS Lambdaを呼び出してCloudFrontのキャッシュを削除(Invalidation)してみた - DevelopersIO

CloudFront の TTL を 0 にしてキャッシュを無効化しておくことも可能ですが、パフォーマンスの観点から一定のキャッシュ保持期間はあった方が良いように思います。

ホスティング

CloudFront + S3

dbt プロジェクト毎に CloudFront ディストリビューションを構築しても良いですが、CloudFront は設定項目が多くて管理がやや大変なので、今回は複数プロジェクトから共用されるものを一つ構築することにしました。

各プロジェクトの dbt Docs には、デフォルトルートオブジェクトとして指定した目次用の index.html からリンクを貼っておくことで遷移できるようにしています。

SAML 認証

ホスティングした dbt Docs は社内メンバーにのみ公開したいので、認証の仕組みを設ける必要があります。これには、弊社インフラチームメンバー (@jirtosterone) が以下リポジトリをベースにカスタマイズしてくれたものを使用して、SAML 認証として実装しています。

• DanielMuller / Cloudfront-Auth-IAM-Identity-Center - GitHub

詳細はリポジトリの内容をご参照頂ければと思いますが、概要は以下の通りです。

• dbt Docs アクセス用に AWS IAM Identity Center の Custom SAML アプリケーションを構築します。アクセスを許可したいメンバーを含む Identity Center グループを、このアプリケーションに紐付けます。
• アプリケーションの SAML メタデータと上記リポジトリを使用して、認証用 Lambda 関数をデプロイします。これは CloudFront ディストリビューションのビヘイビアとして設定され、URL アクセス時にリクエストを処理します。

既存の組織 IdP が存在しない等の理由から、Custom SAML アプリケーションの構築にハードルがある場合には、以下の記事のように Lambda@Edge を用いた Cognito ユーザープール認証 ^[4] を実装するという方法もあるかと思います。

• CloudFront+S3による静的サイトにCognito認証を追加してみた - DevelopersIO
• Lambda@Edgeを使用したCloudFrontのCognito認証を試してみた - DevelopersIO

インフラ構成に関する説明は以上です。

さいごに

dbt Docs をホスティングするための AWS インフラ構成について書いてみました。

いざ全体的に整備しようと思うと必要となるリソースも意外と多いので、実装例の一つとして参考になるものがあれば幸いです。今回は CI/CD 部分も AWS 上で構築してみましたが、CI/CD は GitHub Actions としておいて、ホスティングのみ AWS 上で構築するのも良いかもしれません。

最後まで読んで頂き、ありがとうございました。

参考

• 3分でわかるデータマネジメント【メタデータ管理】 - 株式会社データ総研
• データカタログとは？導入のメリットや使い方、ツールのご紹介 - TROCCO blog
• dbt docsを使ったデータカタログの運用事例紹介 - SpeakerDeck

脚注

1. データマネジメント知識体系ガイド 第二版 改定新版 - 日経 BOOK プラス

2. Documentation - For dbt Docs - dbt Developer Hub

3. About dbt docs commands - dbt Developer Hub

4. User pool authentication flow - Amazon Cognito Developer Guide