dbx からバンドルへの移行

重要

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

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

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

機能の比較

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

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

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

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

ビルド管理

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

バンドルを使用すると、ユーザーは Python wheel ファイルをビルド、デプロイ、および実行できます。ユーザーは、バンドルの databricks.yml ファイル内の組み込み whl エントリを活用できます。

コードの同期、デプロイ、実行

dbx Jobs などのワークスペースリソースの生成とは別に、コードのアップロードを有効にします。Lakeflow

バンドルは、常にコードをアップロードし、ワークスペースリソースを作成または更新します。これにより、デプロイが簡素化され、すでに進行中のジョブのブロック条件を回避できます。

dbx プロジェクトのバンドルへの移行

前述の制限事項と、Databricks Labsの dbxと Databricks Asset Bundle の機能比較を確認したら、 dbx からバンドルに移行する準備が整います。

Databricks では、 dbx プロジェクトの移行を開始するには、 dbx プロジェクトを元のフォルダーに保持し、元の dbx プロジェクトの内容をコピーする別の空白フォルダーを用意することをお勧めします。この別のフォルダが新しいバンドルになります。元のフォルダにある dbx プロジェクトをバンドルに変換し始めてから間違いを犯したり、最初からやり直したりすると、予期しない問題が発生する可能性があります。

手順 1: Databricks CLI をインストールしてセットアップする

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

注記

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

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

ステップ 2: バンドル設定ファイルを作成する

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

Visual Studio Code
PyCharm Professional
IntelliJ IDEA Ultimate

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

注記

前のコメントで、Databricks Asset Bundle 構成 JSON スキーマファイルが異なるパスにある場合は、 bundle_config_schema.json をスキーマファイルへの完全なパスに置き換えます。

前に追加した YAML 言語サーバー機能を使用します。詳細については、YAML 言語サーバーのドキュメントを参照してください。

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

Databricks CLI を使用して bundle schema コマンドを実行し、出力を JSON ファイルにリダイレクトすることで、Databricks Asset Bundle 構成 JSON スキーマファイルを生成します。たとえば、次のように、現在のディレクトリ内に bundle_config_schema.json という名前のファイルを生成します。
Bash
```
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: バンドルを検証する

アーティファクトをデプロイしたり、 Databricks ジョブ、:、または MLOps パイプラインを実行したりする前に、バンドル設定ファイルの構文が正しいことを確認する必要があります。これを行うには、バンドルルートから bundle validate コマンドを実行します。

Bash
databricks bundle validate

情報 bundle validateについては、「 databricks bundle validate」を参照してください。

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

指定したローカルアーティファクトをリモートワークスペースにデプロイするには、バンドルルートから bundle deploy コマンドを実行します。コマンド・オプションが指定されていない場合は、バンドル構成ファイルで宣言されているデフォルト・ターゲットが使用されます。

Bash
databricks bundle deploy

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

Bash
databricks bundle deploy -t development

情報については、 bundle deployについては、「 databricks バンドルのデプロイ」を参照してください。

ヒント

バンドル定義のジョブとパイプラインを Databricks ワークスペース内の既存のジョブとパイプラインにリンクして、同期を維持できます。「 databricks バンドルデプロイバインド」を参照してください。

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

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

Bash
databricks bundle run hello_job

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

Bash
databricks bundle run -t development hello_job

bundle runに関する情報については、「databricks bundle 実行」を参照してください。

(オプション)ステップ 8: GitHub で CI/CD のバンドルを構成する

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

dbx プロジェクト設定の databricks.yml への変換

dbxの場合、プロジェクト設定は、デフォルトではプロジェクトの .dbx フォルダー内の project.json という名前のファイルにあります。「プロジェクトファイル参照」を参照してください。

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

次の例の内容を含む conf/project.json ファイルの場合:

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 ファイルは次のとおりです。

YAML
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 ファイルの場合:

YAML
build:
  python: 'pip'

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

対応する databricks.yml ファイルは次のとおりです。

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

targets:
  default:
    workspace:
      # See an example "workspace" mapping in the preceding section.
    resources:
      jobs:
        workflow1:
          tasks:
            - task_key: task1
              python_wheel_task:
                package_name: some-pkg
                entry_point: some-ep

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

build (ただし、「アセットバンドルを使用した Python wheelファイルの構築Databricks 」を参照してください)

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

access_control_list
custom (代わりに標準のYAMLアンカーを使用してください)
deployment_config
Lakeflow Jobs 2.0 形式 (代わりに Jobs 2.1 形式を使用)
dbx Jinja の特徴
名前ベースのプロパティ

機能の比較​

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

ビルド管理​

コードの同期、デプロイ、実行​

dbx プロジェクトのバンドルへの移行​

手順 1: Databricks CLI をインストールしてセットアップする​

ステップ 2: バンドル設定ファイルを作成する​

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

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

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

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

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

(オプション)ステップ 8: GitHub で CI/CD のバンドルを構成する​

dbx プロジェクト設定の databricks.yml への変換​

dbx デプロイメント設定の databricks.yml への変換​