2026年7月24日、Azure DatabricksのDeclarative Automation Bundlesでは、既定のデプロイエンジンがTerraform engineからDirect Deployment Engineへ変更されます。既存Bundleを安全に移行するには、変更日を待つのではなく、同じターゲット・同じデプロイID・同じCI認証情報を使って事前移行し、databricks bundle planが「変更なし」になることを確認するのが基本です。
移行時にcreateやdelete、意図しない大量のupdateが表示された場合は、そのままデプロイしてはいけません。Bundleの識別情報、リソースID、削除済み設定、手動変更によるドリフト、CIサービスプリンシパルの権限を確認してください。
Direct Deployment Engineへの移行手順は公式に提供されています。一方、Terraform deployment engineは将来削除される予定のため、engine: terraformを設定して変更を先送りする方法は恒久対策になりません。(Microsoft Learn)
2026年7月24日の既定エンジン変更で何が起きるのか
Azure Databricksの公式予告では、2026年7月24日からDeclarative Automation BundlesがDirect Deployment Engineを既定で使用し、Terraform engineを使っているBundleでは移行処理がトリガーされます。Terraform deployment engineは、最終的に利用できなくなる予定です。(Microsoft Learn)
Direct Deployment EngineはTerraform providerを経由せず、Databricks Go SDKを使ってリソースを直接管理します。主な利点は、デプロイの高速化、Terraformやproviderのダウンロード依存の解消、JSON形式による詳細なplan、対応リソース追加の迅速化です。Direct Deployment Engine自体は、Databricks CLI 1.3.0で一般提供されています。(Microsoft Learn)
ただし、次のような既存Bundleは特に事前確認が必要です。
- Databricks CLI 1.3.0より前から運用している
bundle.engineを指定せず、Terraform stateを使ってきた- CIで
DATABRICKS_BUNDLE_ENGINE=terraformを設定している databricks bundle deployment migrateを一度も実行していない- 開発、ステージング、本番で異なるデプロイIDを使っている
- Azure Databricksの画面からジョブやパイプラインを手動変更している
- YAMLから過去の設定項目を削除したことがある
${resources.<type>.<key>.<field>}でID以外の値を参照している
新規Bundleについては、Databricks CLI 1.3.0以降で作成されたものはDirect Deployment Engineが既定です。一度もデプロイされていないBundleには変換元のTerraform stateがないため、migrationコマンドではなく、bundle.engine: directを指定して通常どおりデプロイします。(Microsoft Learn)
移行前に固定しておくべきBundleの識別情報
エンジン移行と同時に、Bundle名、ターゲット名、workspace、root_path、CIのデプロイIDを変更してはいけません。
Declarative Automation Bundlesは、リソース名ではなく、stateに記録されたリソースIDを使って既存リソースを追跡します。また、Bundleの識別には、デプロイするユーザーまたはサービスプリンシパル、Bundle名、ターゲット名、workspace、root_pathが関係します。これらが変わると、同じ名前の既存リソースを更新せず、新しいリソースを作成する原因になります。(Microsoft Learn)
移行前に、少なくとも次の項目を記録してください。
| 確認項目 | 移行前に記録する内容 |
|---|---|
| Bundle名 | bundle.name |
| ターゲット | dev、staging、prodなど |
| workspace | workspace.host |
| Bundle配置先 | workspace.root_path |
| state配置先 | workspace.state_pathを指定している場合はその値 |
| デプロイID | ユーザーまたはサービスプリンシパル |
| 実行ID | run_asのユーザーまたはサービスプリンシパル |
| リソース情報 | ジョブ、パイプラインなどのリソースID |
| CLIバージョン | ローカル環境とCI環境の両方 |
本番環境では、デプロイID以外のユーザーが書き込める/Shared配下を避け、書き込み権限を制限した安定したroot_pathを利用する構成が公式テンプレートでも示されています。(Microsoft Learn)
Databricks CLIのバージョンを揃える
Direct Deployment EngineはDatabricks CLI 0.279.0以降で利用できますが、一般提供された機能として移行するなら、少なくともDatabricks CLI 1.3.0以降に統一するのが安全です。bundle.engine設定はCLI 0.295.0で追加されています。(Microsoft Learn)
まず、開発端末とCIでCLIバージョンを確認します。
databricks version移行完了後は、databricks.ymlで必要なCLIバージョンとDirect Deployment Engineを明示します。
bundle:
name: analytics-bundle
engine: direct
databricks_cli_version: '>= 1.3.0'databricks_cli_versionにはSemantic Versioningの制約を指定できます。条件外のCLIでbundle validateを実行するとエラーになるため、古いCIランナーがTerraform engine前提のまま動き続けることを防止できます。(Microsoft Learn)
なお、bundle.engineとDATABRICKS_BUNDLE_ENGINEの両方が設定されている場合は、YAMLのbundle.engineが優先されます。CI環境変数だけをdirectに変更しても、YAMLにengine: terraformが残っていれば切り替わりません。(Microsoft Learn)
公式手順で既存BundleをDirect Deployment Engineへ移行する
移行はターゲット単位で実施します。dev、staging、prodがある場合、それぞれが別のデプロイ状態を持つため、各ターゲットで確認と移行が必要です。
また、エンジン移行とリソース定義変更を同じコミットに含めないでください。移行専用のブランチまたはコミットを作り、YAMLの業務設定を変更しない状態で検証すると、差分の原因を切り分けやすくなります。
移行前の状態を保存する
最初に、現在の認証ID、Bundle識別情報、デプロイ済みリソースを保存します。
databricks auth describe
databricks current-user me -t prod -o json > deployer-before.json
databricks bundle validate -t prod
databricks bundle summary -t prod --force-pull -o json > bundle-before.jsondatabricks auth describeでは、CLIが利用しているworkspace、認証方式、認証設定の取得元を確認できます。databricks current-user meでは、実際にAPIを呼び出すユーザーまたはサービスプリンシパルを確認できます。(Microsoft Learn)
bundle validateの出力では、Bundle名、ターゲット、workspace、ユーザー、デプロイ先パスが想定どおりか確認してください。
Terraform engineで最後のフルデプロイを実行する
公式手順では、最初にTerraform engineを使ってフルデプロイを実行し、現在のYAML、workspace上のリソース、Terraform stateを同期します。(Microsoft Learn)
Linuxまたは一般的なCI環境では、次のように一時的にTerraform engineを明示できます。
DATABRICKS_BUNDLE_ENGINE=terraform databricks bundle deploy -t prodYAMLにengine: directがすでに書かれている場合は設定側が優先されるため、この処理を行う段階では一時的にTerraform engineへ戻すか、移行前の設定を使用します。
このデプロイで大量の変更が発生する場合は、エンジン移行を続ける前に内容を確認してください。ここでの目的は、機能変更ではなく、Terraform側の状態を最新にすることです。
ローカルstateをバックアップする
migrationコマンドを実行する前に、対象ターゲットのローカルstateを安全な場所へコピーします。
cp -a .databricks/bundle/prod .databricks/bundle/prod.pre-directstateにはworkspaceやリソースに関する情報が含まれるため、Gitリポジトリへコミットせず、アクセスを制限した一時保管領域に保存してください。
migrationコマンドを実行する
次のコマンドで、Terraform stateからDirect Deployment Engine用のstateへ変換します。
databricks bundle deployment migrate -t prodDirect Deployment Engineは、Terraform stateとはスキーマが異なるresources.jsonを使用します。migrationコマンドは既存stateからリソースIDを読み取り、Direct Deployment Engine用のstateへ変換します。これにより、同名のリソースを新規作成するのではなく、既存リソースを継続して管理できる状態を作ります。(Microsoft Learn)
Direct Deployment Engine自体は一般提供されていますが、CLIリファレンスではbundle deployment migrateコマンドがPublic Previewとして記載されています。本番環境へ適用する前に、開発またはステージングターゲットで同じ構成を検証するのが安全です。(Microsoft Learn)
Direct Deployment Engineを明示してplanを実行する
migration後、YAMLをDirect Deployment Engineへ切り替えます。
bundle:
name: analytics-bundle
engine: direct
databricks_cli_version: '>= 1.3.0'続いて、Direct Deployment Engineのplanを実行します。
databricks bundle plan -t prodJSON形式の詳細な差分も保存します。
databricks bundle plan -t prod -o json > bundle-plan-direct.json公式の合格条件は、planが正常終了し、変更が表示されないことです。bundle planは実際の変更を行わず、次のデプロイで作成、更新、削除されるリソースを表示します。(Microsoft Learn)
planの結果をどう判断するか
移行専用コミットであれば、基本的な合格条件は「変更なし」です。
| planの結果 | 判断 | 対応 |
|---|---|---|
| 変更なし | 移行成功の可能性が高い | Direct Deployment Engineでのデプロイへ進む |
updateが少数 | 要確認 | 削除済み設定、手動変更、既定値への復帰を確認 |
大量のupdate | 原則中止 | state変換、CLIバージョン、YAML差分を調査 |
create | 危険 | Bundle識別情報やリソースIDの引き継ぎ失敗を疑う |
delete | 非常に危険 | YAMLからの削除、誤ったターゲット、state不一致を確認 |
| 権限エラー | CI権限不足 | デプロイIDのworkspace・リソース権限を確認 |
| substitutionエラー | 参照方法の差異 | ${resources...}の参照フィールドを確認 |
特にcreateが表示された場合、同じ名前のジョブやパイプラインがworkspaceに存在していても、そのままデプロイしてはいけません。Bundleは名前ではなくstate内のIDでリソースを追跡するため、IDの関連付けに失敗すると重複作成される可能性があります。(Microsoft Learn)
Terraform engineとDirect Deployment Engineで異なる更新動作
Direct Deployment EngineはTerraform engineの単純な内部置き換えではありません。既存リソースを安全に更新できるか判断するには、差分計算と削除済み設定の扱いを理解する必要があります。
YAMLから削除した設定は既定値へ戻る
最も注意すべき違いは、YAMLから設定項目を削除した場合の動作です。
Terraform engineでは、一度設定したフィールドを後からdatabricks.ymlから削除しても、workspace上の値がそのまま残ることがあります。Terraformが明示的に管理しているフィールドだけを更新するためです。
Direct Deployment Engineでは、以前のデプロイスナップショットと現在のYAMLを比較します。そのため、以前存在したフィールドが現在のYAMLから消えていると「削除された設定」と判断され、次回デプロイ時にリソース側の既定値へ戻されます。(Microsoft Learn)
例えば、過去に次のような設定をYAMLで指定し、その後YAMLから削除した場合は注意が必要です。
- スケジュールやトリガーの状態
- 通知設定
- タイムアウト
- 同時実行数
- クラスター設定
- リトライ設定
- アクセス権限
- 実行ID
現在のworkspace上の値を維持したい場合は、「以前の値が残っていること」に依存せず、希望する値をYAMLへ明示してください。
手動変更によるドリフトが検出される
Direct Deployment Engineは、ローカル設定、前回デプロイ時のスナップショット、現在のリモート状態を分けて比較します。
そのため、Azure Databricksの画面からジョブやパイプラインを変更している場合、migration後のplanで差分として表示される可能性があります。手動変更を残したいならYAMLへ反映し、Bundle側を正とするならDirect Deployment Engineによる更新内容を確認したうえで上書きします。(Microsoft Learn)
「planに差分が出たが、YAMLを変更していない」という場合、エンジンの不具合と決めつける前に、workspace上の手動変更と、過去にYAMLから削除したフィールドを確認してください。
リソース参照はID以外も確認する
${resources.jobs.my_job.id}のようなID参照は、一般的にはTerraform engineと同様に解決されます。
一方、Direct Deployment Engineでは、ローカル設定に存在するフィールドはローカル値から、存在しないフィールドはAPIで取得したリモート状態から解決されます。そのため、ID以外のname、パス、生成後フィールドなどをsubstitutionで参照しているBundleは、plan結果と実際の解決値を確認してください。(Microsoft Learn)
リソース所有と実行IDを混同しない
移行時には、次の4つを分けて確認する必要があります。
| 種類 | 意味 |
|---|---|
| デプロイID | CLIからAzure Databricks APIを呼び出すユーザーまたはサービスプリンシパル |
| Bundle識別情報 | Bundle名、ターゲット、workspace、root_pathなど |
| リソース所有・権限 | ジョブやパイプラインの所有者、CAN_MANAGE、CAN_RUNなど |
run_as | ジョブやパイプラインが実行されるときのID |
Direct Deployment Engineへの移行で最優先すべき確認事項は、移行前後で管理対象リソースのIDが変わっていないことです。
移行後に次のコマンドを実行します。
databricks bundle summary -t prod --force-pull -o json > bundle-after.jsonbundle-before.jsonとbundle-after.jsonを比較し、少なくとも次を確認します。
- ジョブやパイプラインのリソースIDが同じ
- Bundle名とターゲットが同じ
- workspace hostが同じ
root_pathが同じ- 同名リソースが重複作成されていない
run_asが意図したIDのまま- 所有者とアクセス権限が意図した状態
- スケジュール、トリガー、通知設定が変わっていない
Bundleのトップレベルpermissionsでは、対応リソースに対してCAN_VIEW、CAN_MANAGE、CAN_RUNを指定できます。ジョブやパイプラインでは、リソース単位でIS_OWNERなどを指定することもできます。ただし、同じユーザー、グループ、サービスプリンシパルをトップレベルとリソースレベルの両方へ重複定義することはできません。(Microsoft Learn)
CIサービスプリンシパルの権限を確認する
ローカル端末でplanが成功しても、CIで同じ結果になるとは限りません。ローカルでは管理者ユーザー、CIでは権限を絞ったサービスプリンシパルを利用しているケースが多いためです。
移行検証は、最終的に本番デプロイを実行するCIの認証情報で行ってください。
CI内で認証IDを記録する
CIジョブに次の確認処理を追加します。
databricks auth describe
databricks current-user me -t prod -o json
databricks bundle validate -t prod
databricks bundle plan -t prod -o json > bundle-plan-direct.jsondatabricks auth describeでは、シークレットを表示する--sensitiveを付けないでください。
Azure Databricksは、無人CI/CDの認証方式として、利用可能であればAzure Managed Identity、次にDatabricks管理サービスプリンシパルのOAuth M2M、次にMicrosoft Entra IDサービスプリンシパルを推奨しています。また、複数workspaceへデプロイする場合は、同じサービスプリンシパルを各workspaceへ参加させる構成が推奨されています。(Microsoft Learn)
CIで確認する権限
CIのデプロイIDには、対象構成に応じて次の権限が必要です。
- 対象workspaceへアクセスできる
- Bundleの
root_pathとstate_pathを読み書きできる - 既存ジョブ、パイプライン、ダッシュボードなどを参照できる
- plan対象リソースの現在状態を取得できる
- 対象リソースを更新できる
- Bundleで指定したpermissionsを設定できる
- 指定した
run_asを利用できる - Unity Catalogリソースを含む場合は必要な権限を持つ
run_as.service_principal_nameを指定するには、対象サービスプリンシパルに対するservicePrincipal/userロールが必要です。(Microsoft Learn)
また、デプロイIDとrun_asが異なる場合、Bundleでサポートされるのはジョブとパイプラインに限られます。ジョブやパイプライン以外のリソースを同じBundleで管理している場合は、デプロイIDとrun_asの構成を再確認してください。(Microsoft Learn)
JSON planをCIの承認ゲートに使う
Direct Deployment Engineでは、JSON形式で生成したplanを、後続のdeployへ渡せます。
databricks bundle plan -t prod -o json > bundle-plan-direct.json内容を承認した後、同じplanを適用します。
databricks bundle deploy -t prod --plan bundle-plan-direct.json--planはDirect Deployment Engine専用です。planとdeployの間にYAMLや変数、CLIバージョン、認証IDを変更しないでください。JSON planには構成情報が含まれる可能性があるため、CI成果物として公開せず、保存期間と閲覧権限を制限します。(Microsoft Learn)
本番デプロイで実行中のジョブやパイプラインを変更したくない場合は、--fail-on-active-runsも利用できます。
databricks bundle deploy -t prod \
--plan bundle-plan-direct.json \
--fail-on-active-runsこのオプションを指定すると、対象のジョブまたはパイプラインが実行中の場合にデプロイを失敗させられます。(Microsoft Learn)
一方、--force-lockは通常の移行で使用しないでください。前回のデプロイが異常終了し、古いロックが残った場合に限って使用するオプションです。通常利用すると、同時デプロイを防止する仕組みを無効化します。(Microsoft Learn)
Direct Deployment Engineで最終デプロイする
planが変更なし、またはすべての差分を承認できたら、Direct Deployment Engineでデプロイします。
公式の基本コマンドは次のとおりです。
databricks bundle deploy -t prodJSON planを承認済みの場合は、次の形でもデプロイできます。
databricks bundle deploy -t prod --plan bundle-plan-direct.jsonこのデプロイにより、Direct Deployment Engine用のstateがworkspaceへ同期されます。(Microsoft Learn)
デプロイ後は、次の確認を行います。
bundle summaryでリソースIDを再確認する- 同名リソースが増えていないことを確認する
- ジョブまたはパイプラインを代表的な条件で実行する
- スケジュールとトリガーの停止・再開状態を確認する
- 通知先と権限を確認する
- CIから次回の
bundle planを実行し、不要なドリフトが出ないことを確認する - 開発、ステージング、本番の各ターゲットで同じ確認を繰り返す
migration後にplanが失敗した場合の戻し方
公式手順では、migration後のplanに問題がある場合、作成されたDirect Deployment Engine用stateを削除します。
rm .databricks/bundle/prod/resources.jsonそのうえで、移行前に保存したstateへ戻し、Terraform engineで原因を調査します。CLIリポジトリの移行文書では、migration時にTerraform stateのバックアップが作成されている場合、そのバックアップを復元する手順も示されています。(Microsoft Learn)
問題が解消するまで、次の操作は避けてください。
createやdeleteを含むplanの適用- Bundle名やターゲット名の変更
- workspace hostの変更
root_pathやstate_pathの変更- デプロイIDの変更
- stateファイルのGitコミット
--force-lockによる強制デプロイ- 本番Bundleの削除と再作成
よくある失敗と対処法
既存リソースがすべてcreateになる
Bundleの識別情報またはstateの引き継ぎに失敗している可能性があります。
確認する項目は、Bundle名、ターゲット、workspace、root_path、デプロイID、migration対象のTerraform stateです。同名リソースがあることを理由にデプロイを続けず、移行前の状態へ戻してください。
YAMLを変更していないのにupdateが表示される
主な原因は、workspace上の手動変更、過去にYAMLから削除したフィールド、Direct Deployment Engineでの既定値復帰、リソース参照の解決方法です。
planのJSONを確認し、維持したい設定をYAMLへ明示します。
ローカルでは成功するがCIで権限エラーになる
ローカルユーザーとCIサービスプリンシパルの権限差が原因です。
CI内でdatabricks current-user meを実行し、実際のデプロイIDを確認します。そのIDに対して、workspace、state配置先、対象リソース、run_asサービスプリンシパルの利用権限を付与してください。
migration対象のstateが見つからない
対象ターゲットを間違えているか、そのBundleがTerraform engineで一度もデプロイされていない可能性があります。
未デプロイの新規Bundleではmigrationコマンドを使わず、次のようにDirect Deployment Engineを明示してデプロイします。(Microsoft Learn)
bundle:
name: new-bundle
engine: direct
databricks_cli_version: '>= 1.3.0'migration後も毎回同じupdateが表示される
リモートAPIが返す値とYAMLの値に差があるか、Direct Deployment Engine側で処理されないフィールドによりドリフトが継続している可能性があります。
CLIを最新の安定版へ更新し、対象リソースに関するDirect Deployment Engineの既知issueを確認してください。Direct Deployment Engineは一般提供されていますが、公式CLIリポジトリでも既知issueの確認先が案内されています。(GitHub)
移行完了の判定チェックリスト
次の条件をすべて満たしたら、Terraform engineへの依存を外せます。
- Databricks CLI 1.3.0以降へ統一した
bundle.engine: directを明示した- CLIバージョン制約を設定した
- Terraform engineで最後のフルデプロイを実行した
bundle deployment migrateをターゲットごとに実行した- Direct Deployment Engineのplanが変更なしになった
- 意図しない
create、delete、大量のupdateがない - 移行前後でリソースIDが一致している
- Bundle名、ターゲット、workspace、
root_pathが変わっていない - CIのデプロイIDが移行前後で同じ
run_asとリソース所有者、permissionsが意図した状態- CIサービスプリンシパルでplanとdeployが成功する
- ジョブ、パイプライン、スケジュール、通知の動作確認が完了した
- 次回planで不要なドリフトが発生しない
- CIからTerraform engine指定やTerraform provider依存を削除した
2026年7月24日の既定変更後もTerraform engineを一時的に明示できる場合がありますが、Terraform deployment engineは将来削除されます。通常リリースの最中に自動移行させるのではなく、公式migration手順、変更なしのplan、リソースID比較、CI権限確認を事前に完了させることが、安全な移行の最短ルートです。(Microsoft Learn)
コメント