データパイプラインの可視化 – dbtドキュメント生成とホスティング

データ活用ことはじめ

2024.11.19

データパイプラインの可視化とドキュメントの充実は、データエンジニアにとって重要な課題です。
複雑なデータフローやモデルを管理しやすくし、チームメンバーや関係者にとって理解しやすい形で提供することは、生産性を大幅に向上させる鍵となります。

今回は、dbt Coreを活用してデータパイプラインのドキュメントを生成・ホスティングする方法について、実際に検証した内容を紹介します。

Contents

dbtとは
dbtドキュメントの生成
ドキュメントのホスティング
- GitHub Pagesでのホスティング
- Amazon S3 + CloudFront でのホスティング
まとめ

１．dbtとは

dbt（data build tool)は、SQLを使用してデータパイプラインの構築や管理を効率化するツールです。
dbtには、オープンソースのdbt Coreと、有償版のSaaS製品であるdbt Cloudの2種類があります。

dbt Coreは、コマンドラインベースで動作し、データ変換タスクの自動化やドキュメントの生成をサポートする無料のOSSツールです。
一方、dbt Cloudは、dbt Coreをベースとし、WebベースのUIから利用できる有償サービスです。

今回は、無料で利用できるdbt Coreを使用して検証を行っています。

dbtはコードで定義されたモデルやドキュメントを、GitHubのようなバージョン管理システムと連携させることができます。
これにより、自動テストやCI/CDの導入、コードからドキュメントを自動生成し常に最新情報を提供するなど、ソフトウェア開発のベストプラクティスをデータエンジニアリングにも取り入れることができます。

２．dbtドキュメントの生成

dbtには、データモデルやパイプラインの詳細なドキュメントを自動生成する機能があります。

dbtを使用することで、生成したドキュメントを一元的に管理し、さらにGitHub PagesやAmazon S3の活用によって、ドキュメントをスムーズに共有・更新できるようになります。

以下に、ドキュメント生成の基本的な手順を説明します。

ドキュメントの定義

dbtでは、モデルに対して説明やメタデータを追加することで、ドキュメントが生成されます。
各モデルやカラムには、descriptionプロパティを使用して説明を記述します。
モデルやカラムに対して説明を追加することで、データの意味や使用方法が明確になり、データ品質の維持に役立ちます。

例えば、以下のようにコメントを追加します。

models/schema.yml

ドキュメントの生成

dbt CLIを使用して、ドキュメントを生成します。
以下のコマンドを実行すると、targetディレクトリ内にドキュメントファイルが生成されます。

dbt docs generate

生成されたドキュメントは、HTMLファイルとして保存され、ローカルでブラウザから確認することができます。

ドキュメントの表示

ドキュメントをローカルで確認するためには、以下のコマンドを実行して、ローカルサーバを起動します。

dbt docs serve

コマンド実行後、ブラウザが自動的に開き、生成されたドキュメントを確認できます。

３．ドキュメントのホスティング

dbtドキュメントをローカルで確認するだけでなく、チームメンバーと共有するためには、適切なホスティング方法を選択する必要があります。

dbt Coreで生成したドキュメントをホスティングする方法として、今回はGitHub PagesとAmazon S3+CloudFrontの2つの方法を検証しました。

GitHub Pages
生成されたHTMLファイルをGitHubリポジトリにアップロードし、GitHub Pageを使って公開する方法です。
この方法は設定が非常に簡単で、特にプロジェクトのバージョン管理と連携させたい場合に便利です。

Amazon S3 + CloudFront
Amazon S3バケットを使ってドキュメントをホスティングし、CloudFrontを利用して高速なコンテンツ配信を実現する方法もあります。
企業向けの大規模な環境では、こちらのアプローチが適しています。

GitHub Pagesでのホスティング

GitHub Pagesは、GitHubリポジトリの静的ファイルをホスティングするサービスです。GitHub Pagesを利用すると、ドキュメントを簡単に公開することができます。

ただし、Pagesに対するアクセス制御が必要な場合は、GitHub Enterpriseが必要です。
特定のチームや組織のみにドキュメントを公開したい場合は、このオプションを検討する必要があります。

GitHub Pagesの設定

リポジトリの設定画面からGitHub Pagesを有効化します。
リポジトリの「Settings」タブに移動し、GitHub Pagesの設定の「Source」オプションで「GitHub Actions」を選択します。

これにより、GitHub ActionsがPagesのソースとして設定されます。

GitHub Actionsワークフローの作成

次に、GitHub Actionsのワークフローを作成して、ドキュメントを自動的にGitHub Pagesにデプロイします。
GitHub Actionsでワークフローを定義することで、手動でドキュメントをアップロードする手間を省き、完全な自動化を実現します。

以下はそのための設定ファイルの例です。
.github/workflows/dbt-docs-pages.yml

actions/upload-pages-artifact:
GitHub Actions内で生成されたビルド成果物をアップロードします。
このアクションにより、一時的に成果物が保存され、次のステップで使用できます。

actions/deploy-pages:
アップロードされた成果物を GitHub Pages にデプロイします。
このアクションを使用することで、デプロイプロセスが自動化され、コードの変更が簡単にサイトに反映されます。

この設定により、mainブランチへのプッシュ時に自動的にドキュメントが生成され、GitHub Pagesにデプロイされます。
さらに、CI/CDパイプラインに組み込むことで、ドキュメントの更新が自動的に反映されるようになります。

Amazon S3+CloudFront でのホスティング

次に、Amazon S3とCloudFrontを使ったホスティング方法です。

Amazon S3でドキュメントをホスティングし、CloudFrontを用いてグローバルに配信することで、スケーラビリティやアクセス制御の柔軟性を持たせることができます。

S3+CloudFront構成の主なメリット

セキュアなHTTPS通信の提供
OACを使用して、CloudFront経由のみでS3からのコンテンツを取得
CloudFrontのキャッシュによるロード時間の短縮およびS3トラフィックコストの削減

S3バケットの作成

まず、S3バケットを作成します。
S3バケットに対するパブリックアクセスはすべてブロックします。

CloudFrontの設定

次に、CloudFrontディストリビューションを作成します。

オリジンドメイン: 作成したS3バケット
オリジンアクセス: Origin access control settings（recommended)
※CloudFront からの認証済みリクエストのみに制限
デフォルトルートオブジェクト: index.html
地理的制限: 許可リスト（Allow list)
※この機能を使うことで、コンテンツへのアクセスを特定

以下は、AWS CDKによる設定のコード例です。

# s3_bucket: s3.Bucket

cloudfront.Distribution(
    self, "distro",
    default_behavior=cloudfront.BehaviorOptions(
        origin=origins.S3BucketOrigin.with_origin_access_control(s3_bucket),
        viewer_protocol_policy=cloudfront.ViewerProtocolPolicy.HTTPS_ONLY
    ),
    default_root_object="index.html",
    geo_restriction=cloudfront.GeoRestriction.allowlist("US", "JP")
)

S3バケットポリシーの設定

S3オリジンへのアクセスをCloudFrontに許可する設定をします。
S2バケットポリシーを使用して、CloudFrontサービスプリンシパル（cloudfront.amazonaws.com)に、バケットへのアクセスを許可します。

以下は、CloudFront OACへの読み取り専用アクセスを許可するS3バケットポリシーの例です。

{
    "Version": "2012-10-17",
    "Statement": {
        "Sid": "AllowCloudFrontServicePrincipalReadOnly",
        "Effect": "Allow",
        "Principal": {
            "Service": "cloudfront.amazonaws.com"
        },
        "Action": "s3:GetObject",
        "Resource": "arn:aws:s3:::<S3 bucket name>/*",
        "Condition": {
            "StringEquals": {
                "AWS:SourceArn": "arn:aws:cloudfront::111122223333:distribution/<CloudFront distribution ID>"
            }
        }
    }
}

“Restrict access to an Amazon Simple Storage Service origin｜AWS．https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-s3.html,（参照2024-09-18）

GitHub Actionsワークフローの作成

GitHub Actionsを設定して、ドキュメントをS3に自動的にデプロイします。

以下はそのための設定例です。

この設定により、mainブランチへのプッシュ時に自動的にドキュメントが生成され、S3バケットにデプロイされます。

４．まとめ

dbtドキュメント生成とホスティングは、プロジェクトの可視性を高めるだけではなく、プロジェクト運営においてしばしば直面する「ドキュメント管理の煩雑さ」や「最新情報の共有の難しさ」といった課題に対する有効な解決策を提供します。

GitHub PagesやAmazon S3+CloudFrontを活用することで、生成したドキュメントをスムーズに共有・更新でき、データの使用やパイプラインの構成を容易に把握できるようになります。
これにより、チーム全体や関係者の間での情報共有が容易になり、データパイプラインの理解と透明性を大いに向上させることができます。

dbtの導入やdbtと各サービスとの連携をご検討の際はシステムエグゼにぜひご相談ください。

※記載されている会社名及び商品名／サービス名は、各社の商標または登録商標です。

データ分析ソリューション