Finatext Tech Blog
📦

dbt private package を GitHub で管理する際の Tips

に公開

はじめに

こんにちは!ナウキャストのデータエンジニアのけびんです。

dbt には、マクロやテストなどを再利用可能な形で配布できる「パッケージ」という便利な機能があります。公開されているパッケージを利用するだけでなく、組織内で共通的に使用するロジックを private package として管理することも可能です。

https://docs.getdbt.com/docs/build/packages

本ブログでは、private な dbt package を GitHub で管理し、ローカル開発環境と CI/CD 環境の両方で利用する際に直面した認証の課題と、その解決方法について紹介します。

TL;DR

  • dbt で private package を GitHub App で利用する際には以下のように HTTPS のURLにトークンを書く必要がある
    # GitHub App のトークンを利用して認証する場合の書き方
    - git: "https://{{env_var('DBT_ENV_SECRET_GIT_CREDENTIAL')}}@github.com/your-org/package.git"
    
  • dbt でパッケージを管理する package.yml の中でも Jinja 記法が利用可能で、環境変数の設定の有無により HTTPS URL と SSH URL を使い分けるようにした
  • package.yml で DBT_ENV_SECRET_ から始まる環境変数を env_var 経由で利用する際には ***** とマスキングするようになっている

背景:なぜ private package が必要だったのか

ナウキャストでは dbt-core を活用しており、現在 50 以上の dbt projects が運用されています。これらのプロジェクトの中には、POS データやクレジットカードデータなど、異なるデータソースを扱うものの、共通して実施すべきデータテストが一定数存在していました。

以下のサイトなどで検索することで既存公開パッケージを利用することもしていますが、ナウキャスト独自のテストを作った方が良い場面がしばしばありました。これらを各プロジェクトで個別に実装すると、メンテナンスコストが増大し、品質のばらつきも生じます。そこで、共通のテストロジックを private package として切り出し、再利用可能な形で提供することにしました。
https://www.elementary-data.com/dbt-test-hub

dbt パッケージの基本

dbt でパッケージを利用する場合、packages.yml ファイルに以下のように記載します。

packages.yml
packages:
  # HTTPS で指定する場合
  - git: "https://github.com/dbt-labs/dbt-utils.git"

  # SSH で指定する場合
  - git: "git@github.com:dbt-labs/dbt-utils.git"

公開リポジトリであればこれで問題ありませんが、private リポジトリの場合は GitHub への認証が必要になります。

課題:ローカルと CI/CD で異なる認証方式

私たちの環境では、以下のような認証方式の違いがありました
この2つのパターンはそれぞれ必要とする package の記載方法が異なるため、何らかの対処が必要でした。

  • ローカル開発環境
    • 各エンジニアのエンジニアの開発環境では基本的には SSH 認証を利用
    • ~/.ssh/config に設定済みの SSH 鍵で認証
    • つまり git@github.com:... 形式の SSH URL を packages.yml に記載したい
  • CI/CD 環境(GitHub Actions)
    • 基本的には GitHub App が発行したトークンで認証
    • 以下のように HTTPS URL を packages.yml に記載したい
      packages.yml
      packages:
        # GitHub App のトークンを利用して認証する際には以下の書き方が必要
        - git: "https://{{env_var('DBT_ENV_SECRET_GIT_CREDENTIAL')}}@github.com/dbt-labs/awesome_repo.git" # git HTTPS URL
      

解決策①:Jinja による条件分岐

dbt SQL モデルの中では Jinja テンプレートの記法を使用している方も多いと思いますが、実は dbt では 、packages.yml や profiles.yml の中でも Jinja テンプレートの記法を使用できます。これを活用して、DBT_ENV_SECRET_GIT_CREDENTIAL という環境変数の有無によって URL を切り替えることを考えました。

packages.yml
packages:
  - git: "{% if env_var('DBT_ENV_SECRET_GIT_CREDENTIAL', '') != '' %}https://{{env_var('DBT_ENV_SECRET_GIT_CREDENTIAL', '')}}@github.com/your-org/package.git{% else %}git@github.com:your-org/package.git{% endif %}"

git:の中の文字列で一行になってしまっており少し読みにくいですが、やっていることはシンプルで以下の分岐を行っているだけです。

  • DBT_ENV_SECRET_GIT_CREDENTIAL 環境変数が設定されている場合
    • 基本的には GitHub Actions 上で、 GitHub App のトークンを利用している場合に相当
    • HTTPS + トークン認証
  • 設定されていない
    • ローカルでの実行などの場合に相当
    • SSH 認証

基本的にはこれで解決なのですが、これがうまく動作しないコーナーケースがありました。

問題:DBT_ENV_SECRET_ prefix の特殊な挙動

実は、dbt には DBT_ENV_SECRET_ で始まる環境変数を env_var() で取り扱う際に特殊な処理を行なっています。

Secrets
For certain configurations, you can use "secret" env vars. Any env var named with the prefix DBT_ENV_SECRET will be:

  • Available for use in profiles.yml + packages.yml, via the same env_var() function
  • Disallowed everywhere else, including dbt_project.yml and model SQL, to prevent accidentally writing these secret values to the data warehouse or metadata artifacts
  • Scrubbed from dbt logs and replaced with *****, any time its value appears in those logs (even if the env var was not called directly

https://docs.getdbt.com/reference/dbt-jinja-functions/env_var#secrets

最後のポイントが重要でセキュリティのために値が自動的にマスクされます。これにより、条件分岐 {% if env_var('DBT_ENV_SECRET_GIT_CREDENTIAL', '') != '' %} が期待通りに機能しないケースがありました。

解決策②:フラグ変数による回避

そこで、事前に環境変数の有無を判定し、別の変数に格納する方法をとりました。

# CI/CD のワークフロー内で実行
SECRET_FLAG=$([ "${DBT_ENV_SECRET_GIT_CREDENTIAL}" = "" ] && echo "0" || echo "1")
export SECRET_FLAG

そして、packages.yml では SECRET_FLAG を使って分岐し、 packages.yml の中では DBT_ENV_SECRET_GIT_CREDENTIAL は基本的に値をそのまま出力するのみとなるようにしました。

packages.yml
packages:
  - git: "{% if env_var('SECRET_FLAG', '0') | int == 1 %}https://{{env_var('DBT_ENV_SECRET_GIT_CREDENTIAL', '')}}@github.com/your-org/package.git{% else %}git@github.com:your-org/package.git{% endif %}"

これにより、目的にあった環境ごとの利用する GitHub のURLの切り替えが実現できるようになりました。

まとめ

dbt の private package を運用する際にぶつかった課題と対処方法について紹介しました。GitHub で dbt private package を管理する場合、アクセス経路によって SSH URL と HTTPS URL の両方を使い分けたくなることがありますが、 Jinja テンプレートの記法と env_var を適切に利用することで対処しました。

同様の課題に直面している方の参考になれば幸いです。

参考資料

https://blog.dataengineerthings.org/handling-private-dbt-packages-on-a-dbt-project-9e99b104a051

GitHubで編集を提案
Finatext Tech Blog
Finatext Tech Blog

Discussion