データ基盤

Databricks宣言型自動化バンドルとは？旧アセットバンドルの仕組み

2026/10/12 シリーズ「Databricks 入門」 第8回 / 全9回

🤖 AIが執筆しています

orders-pipeline/
├── databricks.yml   バンドルの設定
└── src/
    ├── bronze.py
    ├── silver.py
    └── gold.py

bundle:
  name: orders_pipeline

resources:
  jobs:
    orders_nightly:
      name: orders_nightly
      schedule:
        quartz_cron_expression: "0 0 2 * * ?"   # 毎日 2 時
        timezone_id: Asia/Tokyo
      tasks:
        - task_key: bronze
          notebook_task:
            notebook_path: ./src/bronze.py
        - task_key: silver
          depends_on:
            - task_key: bronze
          notebook_task:
            notebook_path: ./src/silver.py
        - task_key: gold
          depends_on:
            - task_key: silver
          notebook_task:
            notebook_path: ./src/gold.py

targets:
  dev:
    mode: development
    default: true
    workspace:
      host: https://dev.cloud.databricks.com
  prod:
    mode: production
    workspace:
      host: https://prod.cloud.databricks.com
    run_as:
      service_principal_name: <実行用のサービスプリンシパルのアプリケーション ID>

宣言型自動化バンドルとは：ジョブとコードを一つの単位でデプロイする

Databricks の文書は、バンドルを、ソース管理、コードレビュー、テスト、CI/CD といったソフトウェア工学の慣行をデータと AI のプロジェクトに取り入れるためのツールだとし⁹、インフラをコードで管理する（IaC）方法の一つと位置づける⁹。バンドルは Databricks CLI（コマンドラインのツール）の機能で、ふつうは手元で作り、CLI で対象のワークスペースにデプロイする⁹。2025 年 10 月からは、CLI を入れずにワークスペースの中でバンドルを編集し、デプロイすることもできる¹。

バンドルに含まれるものには、処理を書いたソースファイルと、ジョブやパイプライン、ダッシュボードなどの Databricks の資源の定義があり、テストなども含められる⁹。処理のコードはソースファイルに、ジョブなどの資源の定義は databricks.yml の resources に書く。二つは同じプルリクエストで変わるので、ジョブのスケジュールの変更も、それが動かすコードの横でレビューされる¹⁰。

ジョブそのものは、Lakeflow ジョブという Databricks の機能である。この機能は 2025 年 6 月まで Databricks Jobs（Workflows とも呼ばれた）という名前だった¹¹。バンドルは、ジョブを作るための別のツールであって、ジョブを動かす仕組みではない。

ジョブ：タスク、依存関係、トリガー

Lakeflow ジョブは、ジョブ、タスク、トリガーの三つの概念からなる¹²。タスクはジョブの中の一つの処理の単位で、ノートブック、Python のスクリプト、SQL、パイプライン、別のジョブなどを動かせる¹²¹³。タスクの間の依存関係は、有向非巡回グラフ（DAG、矢印が輪にならないつながり）で表される¹²。

トリガーは、ジョブをいつ動かすかを決める。決まった時刻に動かすスケジュールのほか、ストレージに新しいファイルが届いたとき、元の表が更新されたとき、前の実行が終わるたびに動かす方法がある¹⁴。

ジョブを動かすコンピュートについて、文書は、人が対話的に使う汎用のコンピュートを本番のジョブに使うことを勧めておらず¹⁵、サーバーレスのコンピュートに対応するタスクでは、それを既定として使う¹⁵。費用の面では、対話的でない処理はジョブのコンピュートの方が汎用より大幅に安い¹⁶。

開発モード：開発者ごとに別のジョブを作る

ターゲットの mode: development は、開発モードを指定する。開発モードでデプロイすると、Databricks は次のことを行う⁷。

• デプロイしたジョブやパイプラインの名前の前に [dev <開発者の短い名前>] を付け、dev のタグを付ける。
• デプロイした資源のスケジュールとトリガーを、すべて止める。
• 同じジョブを同時にいくつも動かせるようにする。
• デプロイのロック（同時にデプロイして衝突するのを防ぐ仕組み）を外す。

バンドルは、名前とターゲットとデプロイした人の三つで区別される¹⁷。既定のデプロイ先は /Workspace/Users/<デプロイした人>/.bundle/<バンドル名>/<ターゲット名> なので⁶、別の開発者が同じバンドルを同じターゲットにデプロイすると、その開発者の下に別のファイルと別のジョブができる。それぞれのジョブとファイルは互いに上書きしない。ただし、それぞれがデプロイするジョブに同じ書き込み先の表を指定していれば、ジョブとファイルが別でも、データは同じ表に書き込まれる。表まで分けるには、Databricks が勧めるように、開発者ごとのスキーマ（例：dev_${user_name}）を変数で切り替える¹⁸。Mechanical Rock の Maciej Tarsa は、開発モードなら複数の人が同じバンドルを互いの邪魔をせずに扱えると評価している⁵。

デプロイしたジョブは、名前ではなく、デプロイ先の state に記録した ID で追跡される¹⁹。そのため、設定からジョブを消してデプロイし直すと、そのジョブはワークスペースからも消える¹⁹。

本番へのデプロイ：デプロイする者と動かす者を分ける

mode: production は、本番運用モードを指定する。このモードは、デプロイする前にいくつかを確かめるだけで、開発モードのように設定を変えはしない。確かめるのは、ターゲットに Git のブランチを指定した場合に今のブランチがそれと一致するか、パイプラインが開発用の設定になっていないか、サービスプリンシパルを使わない場合に誰がどの権限を持つかが書かれているか、である⁷。本番運用モードが、サービスプリンシパルを作ったり、CI からのデプロイを強制したりするわけではない。

Databricks は、本番のデプロイにサービスプリンシパルを使うよう勧め、本番運用モードの文書は、run_as にサービスプリンシパルを書けばそれを強制できるとする⁷。run_as は、バンドルをデプロイする ID と、ジョブを動かす ID を分ける設定である²⁰。run_as を書いたターゲットでは、ジョブはデプロイした人ではなく、run_as に書いた ID の権限で動く。ジョブの実行者を人にしておくと、その人が組織を離れたり権限が変わったりしたときに、ジョブが失敗することがある²¹。開発者向けの推奨の文書は、さらに、デプロイ用と実行用で別のサービスプリンシパルを使い、デプロイ用には最小限のデータの権限しか与えないよう勧めている¹⁸。デプロイ用のサービスプリンシパルには、実行用のサービスプリンシパルを使う権限（CAN_USE）が要る²⁰。

本番のデプロイ先には、/Shared の下を使わない。/Shared はワークスペースの全員が書き込めるので、本番のコードやジョブの定義を誰でも書き換えられるからである⁶。文書は、本番のデプロイ先への書き込みをデプロイ用のサービスプリンシパルだけに絞るよう勧めている⁶。

CI からのデプロイでは、CI が Databricks に認証するための資格情報が要る。Databricks は、CI/CD の認証にワークロード ID フェデレーションを勧めている²²。これは、GitHub Actions などの CI が自分の身元を示すために発行するトークンを、Databricks のトークンと交換する方法で、Databricks の秘密の値を CI に保存せずに済む²³。

Databricks は、開発、ステージング、本番のワークスペースを分けることを勧めている²²。データエンジニアが 5 人までの小さなチームなら、開発と本番の二つから始めてよいとする¹⁸。

画面で直すとどうなるか

本番のジョブの設定を、急いで画面で変えたいとする。バンドルでデプロイしたジョブは、ジョブの画面では既定で読み取り専用で、直すには設定ファイルを直してデプロイし直す²⁴。どうしても画面で直す場合は、画面の「Disconnect from source」（ソースから切り離す）を押して、ジョブをバンドルから切り離す²⁴。ただし、画面での変更はバンドルの設定には反映されず、バンドルでデプロイし直すとジョブは再びバンドルにつながる²⁴。新しいデプロイの仕組みは、ワークスペースの側の今の状態も最後にデプロイした時点の設定と比べるので²⁵、設定ファイルにも同じ変更を書かない限り、次のデプロイでジョブは設定ファイルのとおりに戻る。

ファイルの扱いは、これと違う。Databricks のコミュニティでの質問への回答によれば、デプロイは手元で変わったファイルだけを上げるので、ワークスペースの側でファイルを直し、手元の同じファイルを変えていなければ、デプロイし直してもワークスペースの側の変更は残る²⁶。同じ回答は、バンドルでは手元のリポジトリが正であるとし、ワークスペースを手元と完全に一致させたいなら、デプロイした先のファイルを消してからデプロイし直すよう勧めている²⁶。

画面で作った既存のジョブをバンドルに移すには、databricks bundle generate でそのジョブの設定ファイルを作り、databricks bundle deployment bind で既存のジョブと結び付ける²。結び付けずにデプロイすると、既存のジョブは更新されず、新しいジョブがもう一つできる¹⁹。

失敗した実行を直す：修復実行

修復実行を使うと、失敗したタスクと、それに依存するタスクだけを動かし直せる²⁷。修復実行は、二つ以上のタスクからなるジョブでだけ使える²⁷。

修復実行は、失敗したタスクを初めから動かし直し、タスクを冪等（何度動かしても結果が同じ）にはしない²⁷。タスクが表に行を追記する処理で、途中まで書いたところで失敗していたなら、修復実行でそのタスクが初めから動き、すでに書いた行がもう一度追記される。文書は、修復の前に各タスクが何を書くかを確かめ、重複が問題になる場所では追記ではなく上書きやマージを使うよう勧めている²⁷。

Git フォルダーとの違い

Databricks には、ワークスペースの中で Git を扱う Git フォルダー（以前の名前は Repos）もある²⁸。Git フォルダーは、ワークスペースの中でリポジトリを複製し、ブランチを作り、変更をコミットして送るためのツールである²⁸。

Git フォルダーで管理されるのはコードだけで、Git フォルダーのファイルを動かすジョブの設定は、ソース管理の外に残る²⁹。ジョブのタスクに Git のリポジトリを直接指定する方法でも、タスクの並び、コンピュートの設定、スケジュールはソース管理の外にある²⁹。Databricks は CI/CD にバンドルを勧め、コードだけをデプロイしたい場合には、本番用の Git フォルダーを使う方法を挙げている³⁰²⁹。本番用の Git フォルダーは、変更がデプロイ用のブランチに合流したときに自動で更新し、人は書き換えないものとしている³⁰。

ジョブの Git の文書は、本番のジョブでは Git フォルダーの中のパスより、タスクに Git のリポジトリを直接指定するよう勧める³¹。一方、バンドルの文書は、バンドルではこの直接の指定を勧めない¹³。バンドルは、デプロイしたジョブが手元と同じファイルを持つことを前提にしているからである¹³。バンドルを使うなら、コードはバンドルと一緒にデプロイすることになる。

デプロイの仕組み：Terraform から直接の API 呼び出しへ

バンドルは、当初、Terraform（インフラをコードで管理する別のツール）の Databricks 向けの部品の上に作られていた²⁵。2026 年 6 月に、Terraform を使わずに Databricks の API を直接呼ぶデプロイの仕組みが一般提供になり、新しいバンドルの既定になった¹²⁵。CLI の 1.14 からは、Terraform の仕組みを使っていた既存のバンドルも、デプロイのときに自動で新しい仕組みに移され、1.20.0 では Terraform を使う仕組みそのものが取り除かれた²⁵。

利用者から見える違いの一つは、設定から消した項目の扱いである。Terraform の仕組みでは、databricks.yml から項目を消しても、ワークスペースの値は前のまま残った。新しい仕組みでは、消した項目は既定の値に戻る²⁵。既存のバンドルも自動で移されるので、残しておきたい値は、設定に明示して書いておく必要がある。

運用の優秀性：自動化と、設定のコード化

ジョブの管理や CI/CD は、Databricks の基本原則ではなく、Databricks が示す評価の柱（Well-Architected）の一つ、オペレーショナルエクセレンス（運用の優秀性）が扱う³²。この柱の文書は、DevOps と MLOps の両方で CI/CD のパイプラインを使って作り、リリースすることを挙げ、デプロイと処理を自動化すると、手順がそろい、人の誤りが減り、繰り返しやすくなるとする³²。そこには、設定のずれ（ドリフト）を避けるために設定をコードで管理することも含まれる³²。画面で直したジョブの設定が次のデプロイで設定ファイルのとおりに戻ることは、この考え方に沿っている。

この柱の推奨の文書と、開発者向けの推奨の文書とでは、ツールの分担の書き方が違う。前者は、ジョブのデプロイと管理には Terraform の Databricks 向けの部品が推奨のツールだと書く³³。同じ日に更新された後者は、Terraform はクラウドの側の資源と、ワークスペースの作成のような管理者の操作にだけ使い、それ以外の Databricks の資源にはバンドルを使うよう勧めている¹⁸。

開発者向けの推奨の文書は、バンドルの大きさについても、大きな一つのバンドルより小さなバンドルを勧め、持ち主、権限、変更の周期、戻す単位が違うものは分けるよう勧めている¹⁸。クラウドとの境にある資源では、今の新しいデプロイの仕組みは外部の保存場所（external location）を扱えるようになった²⁵。ただし、その前提となる認証の設定（storage credential）は、バンドルで定義できる資源の一覧に無く、外部の保存場所の設定から名前で参照するだけである³⁴。

外から見た宣言型自動化バンドル

バンドルを支持する実務者は、環境の分け方と、一つの単位でデプロイできる点を評価する。Junaid Effendi は、ジョブを Terraform からバンドルに移した経験から、Terraform の状態の問題で開発へのデプロイが他のチームの汎用クラスターを再起動させたことなどを挙げ、デプロイと保守がしやすく必要な技術も少ないとしてバンドルを勧める³⁵。一方で Effendi は、コードと一緒にデプロイする代わりに、ジョブの設定だけを変えるときも、テストやリリースの段を飛ばす設定を CI に足す必要があると書いている³⁵。Tarsa は、Databricks を使っていてバンドルを使っていないなら損をしていると書くが、所属する Mechanical Rock は Databricks を扱うコンサルティング会社である⁵。留保を付ける側では、Dateonic の Łukasz Wybieralski が、バンドルはそれだけでは安全なリリースの網にならず、テスト、承認、監視、それまでの Git の版でデプロイし直す手順が別に要ると書く¹⁰。Rabobank の技術ブログでは、クラウドエンジニアの Gijs Reijn が、2025 年 3 月の時点で、リポジトリのファイルが 2,000 を超えると、パイプラインからのデプロイがワークスペースの API の回数の上限に当たり、429 や 504 のエラーが続いたと書いている³⁶。手元から試したときは、最初の同期の後は作った・変えた・消したファイルだけが同期されるので、上限には当たらなかったという³⁶。

これらは、どれも一人の実務者の経験か、Databricks に関わる会社の記事である。バンドルや Lakeflow ジョブを、Databricks に関わらない第三者が手法を示して評価したものは、査読付きの論文と方法を示した調査を探した範囲では見つからなかった。新しいデプロイの仕組みでデプロイが最大 40% 速くなるという数字も、測り方の示されていない Databricks 自身の説明である²⁵。

この記事はAIが執筆しています。内容には誤りが含まれる可能性があります。ご注意ください。