dbx からバンドルに移行する

[アーティクル]
10/09/2024

重要

Databricks では、Databricks Labs の dbx ではなく、Databricks アセットバンドルを使用することが推奨されています。 dbx に関する関連記事は廃止され、更新されない可能性があります。

この記事では、Databricks Labs による dbx のプロジェクトを Databricks アセットバンドルに移行する方法について説明します。 Databricks Labs による dbx の概要に関するページと、「Databricks アセットバンドルとは」をご覧ください。.

移行する前に、Databricks Labs による dbx と Databricks アセットバンドルの間での次の制限事項および機能の比較に注意してください。

制限事項

Databricks Labs による dbx でサポートされる次の機能は、Databricks アセットバンドルでは制限されるか、存在しないか、回避策が必要です。

JAR 成果物のビルドは、バンドルではサポートされていません。
ワークスペースパスの FUSE 表記は、バンドルではサポートされていません (例: /Workspace/<path>/<filename>)。ただし、/Workspace/${bundle.file_path}/<filename> などの表記を使うことで、デプロイの間に FUSE スタイルのワークスペースパスを生成するようバンドルに指示できます。

機能比較

移行を行う前に、Databricks Labs による dbx の次の機能が Databricks アセットバンドルでどのように実装されているかに注意してください。

テンプレートとプロジェクト

dbx では、Jinja テンプレートのサポートが提供されます。デプロイ構成に Jinja テンプレートを含めて、環境変数をインラインまたは変数ファイルで渡すことができます。推奨されませんが、dbx では、カスタムユーザー関数の実験的なサポートも提供されます。

バンドルでは、構成の再利用のために Go テンプレートのサポートが提供されます。ユーザーは、事前構築済みのテンプレートに基づいてバンドルを作成できます。カスタムユーザー関数を除き、テンプレートはほぼ完全に同じです。

ビルドの管理

dbx では、pip wheel、Poetry、Flit によってビルドのサポートが提供されます。ユーザーは、プロジェクトの deployment.yml ファイルの build セクションでビルドオプションを指定できます。

バンドルを使って、ユーザーは Python ホイールファイルをビルド、デプロイ、実行できます。ユーザーは、バンドルの databricks.yml ファイルで組み込みの whl エントリを利用できます。

コードを同期、デプロイ、実行する

dbx を使うと、Azure Databricks ジョブなどのワークスペースリソースの生成とは別に、コードをアップロードできます。

バンドルは常に、コードのアップロードとワークスペースリソースの作成または更新を同時に行います。これにより、デプロイが簡略化され、既に進行中のジョブの状態がブロックされなくなります。

dbx プロジェクトをバンドルに移行する

前に示した Databricks Labs による dbx と Databricks アセットバンドルの間の制限事項と機能の比較に注意したら、dbx からバンドルに移行できる状態になります。

Databricks では、dbx プロジェクトの移行を始めるにあたり、dbx プロジェクトを元のフォルダーに残しておき、空のフォルダーを別に作成して元の dbx プロジェクトの内容をコピーすることが推奨されています。この別のフォルダーが新しいバンドルになります。元のフォルダーで dbx プロジェクトからバンドルへの変換を始めた場合、間違いを犯したり、最初からやり直したりすると、予期しない問題が発生する可能性があります。

ステップ 1: Databricks CLI をインストールして設定する

Databricks アセットバンドルは、Databricks CLI バージョン 0.218.0 以降で一般提供されています。 Databricks CLI バージョン 0.218.0 以降を既にインストールして設定してある場合は、ステップ 2 に進んでください。

Note

バンドルは、Databricks CLI バージョン 0.18 以前とは互換性がありません。

Databricks CLI バージョン 0.218.0 以降をインストールまたは更新します。「Databricks CLI のインストールまたは更新」を参照してください。
たとえば、Azure Databricks 個人用アクセストークン認証を使って、ターゲットの Azure Databricks ワークスペースでの認証用に Databricks CLI を設定します。他の種類の Azure Databricks 認証については、「Databricks CLI の認証」をご覧ください。

手順 2: バンドル構成ファイルを作成する

YAML ファイルや JSON スキーマファイルに対応する Visual Studio Code、PyCharm Professional、IntelliJ IDEA Ultimate などの IDE を使用している場合は、IDE を使用してバンドル構成ファイルを作成するだけでなく、次のようにファイルの構文と書式設定を確認し、コード補完のヒントを提供できます。

Visual Studio Code

Visual Studio Code Marketplace から YAML 拡張機能をインストールするなどして、Visual Studio Code に YAML 言語サーバーのサポートを追加します。
Databricks CLI を使用して bundle schema コマンドを実行し、出力を JSON ファイルにリダイレクトして、Databricks アセットバンドル構成 JSON スキーマファイルを生成します。たとえば、次のように、現在のディレクトリ内で bundle_config_schema.json という名前のファイルを生成します。
```
databricks bundle schema > bundle_config_schema.json
```
Visual Studio Code を使用し、現在のディレクトリ内にバンドル構成ファイルを作成するか、開きます。通常、このファイルの名前は databricks.yml になります。
バンドル構成ファイルの先頭に次のコメントを追加します。
```
# yaml-language-server: $schema=bundle_config_schema.json
```
Note

前のコメントで、Databricks アセットバンドル構成 JSON スキーマファイルが別のパスにある場合は、bundle_config_schema.json をスキーマファイルへの完全パスに置き換えます。
前に追加した YAML 言語サーバー機能を使用します。詳細については、YAML 言語サーバーのドキュメントを参照してください。

PyCharm Professional

Databricks CLI を使用して bundle schema コマンドを実行し、出力を JSON ファイルにリダイレクトして、Databricks アセットバンドル構成 JSON スキーマファイルを生成します。たとえば、次のように、現在のディレクトリ内で bundle_config_schema.json という名前のファイルを生成します。
```
databricks bundle schema > bundle_config_schema.json
```
バンドル構成 JSON スキーマファイルが認識されるように PyCharm を構成し、「Configure a custom JSON schema (カスタム JSON スキーマを構成する)」の手順に従って、JSON スキーママッピングを完了します。
PyCharm を使用してバンドル構成ファイルを作成かるか、開きます。通常、このファイルの名前は databricks.yml になります。入力すると、PyCharm により JSON スキーマの構文と書式設定がチェックされ、コード補完のヒントが提供されます。

IntelliJ IDEA Ultimate

Databricks CLI を使用して bundle schema コマンドを実行し、出力を JSON ファイルにリダイレクトして、Databricks アセットバンドル構成 JSON スキーマファイルを生成します。たとえば、次のように、現在のディレクトリ内で bundle_config_schema.json という名前のファイルを生成します。
```
databricks bundle schema > bundle_config_schema.json
```
バンドル構成 JSON スキーマファイルが認識されるように IntelliJ IDEA を構成し、「カスタム JSON スキーマを構成する」の手順に従って、JSON スキーママッピングを完了します。
IntelliJ IDEA を使用してバンドル構成ファイルを作成かるか、開きます。通常、このファイルの名前は databricks.yml になります。入力すると、IntelliJ IDEA により JSON スキーマの構文と書式設定がチェックされ、コード補完のヒントが提供されます。

ステップ 3: dbx プロジェクト設定を databricks.yml に変換する

dbx プロジェクトの .dbx/project.json ファイルの設定を、バンドルの databricks.yml ファイルでの同等の設定に変換します。詳しくは、「dbx のプロジェクト設定を databricks.yml に変換する」をご覧ください。

ステップ 4: dbx のデプロイ設定を databricks.yml に変換する

dbx プロジェクトの conf フォルダーの設定を、バンドルの databricks.yml ファイルでの同等の設定に変換します。詳しくは、「dbx のデプロイ設定を databricks.yml に変換する」をご覧ください。

ステップ 5: バンドルを検証する

成果物をデプロイする前、または Azure Databricks ジョブ、Delta Live Tables パイプライン、MLOps パイプラインを実行する前に、バンドル構成ファイルの構文が正しいことを確認する必要があります。これを行うには、バンドルルートから bundle validate コマンドを実行します。

databricks bundle validate

bundle validate の詳細については、「バンドルを検証する」を参照してください。

ステップ 6: バンドルをデプロイする

指定したローカル成果物をリモートワークスペースにデプロイするには、バンドルルートから bundle deploy コマンドを実行します。コマンドオプションを何も指定しないと、バンドル構成ファイルで宣言されている既定のターゲットが使われます。

databricks bundle deploy

特定のターゲットのコンテキスト内に成果物をデプロイするには、バンドル構成ファイル内で宣言されているターゲットの名前と共に -t (または --target) オプションを指定します。たとえば、development という名前で宣言されたターゲットの場合、

databricks bundle deploy -t development

bundle deploy の詳細については、「バンドルをデプロイする」を参照してください。

ヒント

バンドルで定義されたジョブとパイプラインを Azure Databricks ワークスペース内の既存のジョブとパイプラインにリンクして、それらを同期させることができます。「バンドルリソースをバインドする」を参照してください。

ステップ 7: バンドルを実行する

特定のジョブまたはパイプラインを実行するには、バンドルルートから bundle run コマンドを実行します。バンドル構成ファイル内で宣言されているジョブまたはパイプラインを指定する必要があります。 -t オプションを指定しないと、バンドル構成ファイル内で宣言されている既定のターゲットが使われます。たとえば、既定のターゲットのコンテキスト内で hello_job という名前のジョブを実行するには、次のようにします。

databricks bundle run hello_job

development という名前で宣言されたターゲットのコンテキスト内で hello_job という名前のジョブを実行するには、次のようにします。

databricks bundle run -t development hello_job

bundle runの詳細については、「ジョブまたはパイプラインを実行する」を参照してください。

(省略可能) ステップ 8: GitHub で CI/CD 用にバンドルを構成する

CI/CD に GitHub を使う場合は、GitHub Actions を使うことで、特定の GitHub ワークフローイベントや他の条件に基づいて、databricks bundle deploy コマンドと databricks bundle run コマンドを自動的に実行できます。「Databricks アセットバンドルと GitHub Actions を使用して CI/CD ワークフローを実行する」を参照してください。

dbx のプロジェクト設定を databricks.yml に変換する

dbx の場合、プロジェクトの設定は、既定ではプロジェクトの .dbx フォルダーの project.json という名前のファイルにあります。「プロジェクトファイルリファレンス」をご覧ください。

バンドルの場合、バンドルの構成は、既定ではバンドルのルートフォルダー内の databricks.yml という名前のファイルにあります。「Databricks アセットバンドルの構成」をご覧ください。

次の例のような内容の conf/project.json ファイルの場合:

{
  "environments": {
    "default": {
      "profile": "charming-aurora",
      "storage_type": "mlflow",
      "properties": {
        "workspace_directory": "/Workspace/Shared/dbx/charming_aurora",
        "artifact_location": "/Workspace/Shared/dbx/projects/charming_aurora"
      }
    }
  },
  "inplace_jinja_support": true
}

対応する databricks.yml ファイルは次のようになります。

bundle:
  name: <some-unique-bundle-name>

targets:
  default:
    workspace:
      profile: charming-aurora
      root_path: /Shared/dbx/charming_aurora
      artifact_path: /Shared/dbx/projects/charming_aurora
    resources:
      # See an example "resources" mapping in the following section.

この例で先の conf/project.json ファイルに含まれる次のオブジェクトは、databricks.yml ファイルではサポートされておらず、回避策はありません。

inplace_jinja_support
storage_type

conf/project.json ファイルにおいて追加で許可される次のオブジェクトは、databricks.yml ファイルではサポートされておらず、回避策はありません。

enable-context-based-upload-for-execute
enable-failsafe-cluster-reuse-with-assets

dbx のデプロイ設定を databricks.yml に変換する

dbx の場合、デプロイの設定は、既定ではプロジェクトの conf フォルダー内のファイルにあります。「デプロイファイルリファレンス」をご覧ください。既定では、デプロイ設定ファイルのファイル名は次のいずれかです。

deployment.yml
deployment.yaml
deployment.json
deployment.yml.j2
deployment.yaml.j2
deployment.json.j2

バンドルの場合、デプロイの設定は、既定ではバンドルのルートフォルダー内の databricks.yml という名前のファイルにあります。「Databricks アセットバンドルの構成」をご覧ください。

次の例のような内容の conf/deployment.yml ファイルの場合:

build:
  python: "pip"

environments:
  default:
    workflows:
      - name: "workflow1"
        tasks:
          - task_key: "task1"
            python_wheel_task:
              package_name: "some-pkg"
              entry_point: "some-ep"