Databricksアセットバンドルテンプレート

この記事では、 Databricks CLI バージョン 0.218.0 以降で動作する Databricks Asset Bundle テンプレートの構文について説明します。バンドルを使用すると、Databricks ワークフローをプログラムで管理できます。 「Databricks アセット バンドルとは何か?」を参照してください。

バンドル テンプレートを使用すると、ユーザーは、フォルダー構造、ビルド ステップとタスク、テスト、および開発環境のデプロイメント パイプライン全体に共通するその他の DevOps Infrastructure-as-Code (IaC) 属性を確立することにより、一貫性があり、繰り返し可能な方法でバンドルを作成できます。

たとえば、インストール時に時間のかかるコンパイル ステップを含むカスタム パッケージを必要とする Databricks ジョブを定期的に実行する場合、カスタム コンテナー環境をサポートするバンドル テンプレートを作成することで開発ループを高速化できます。

バンドル・テンプレートは、作成されるバンドルのディレクトリー構造を定義し、 databricks.yml.tmpl 構成ファイル・テンプレートと、ユーザー・プロンプト変数を含む databricks_template_schema.json ・ファイルが含まれます。

テンプレートに基づくバンドルの作成

このセクションでは、バンドル テンプレート (Databricks 当然バンドル テンプレートまたはカスタム バンドル テンプレート) の使用方法について説明します。

デフォルトのバンドル テンプレートを使用する

Databricks のデフォルト バンドル テンプレートを使用してバンドルを作成するには、 Databricks CLI bundle initコマンドを使用して、使用するデフォルト テンプレートの名前を指定します。 たとえば、次のコマンドは、デフォルトの Python バンドル テンプレートを使用してバンドルを作成します。

databricks bundle init default-python

デフォルトのテンプレートを指定しない場合、 bundle initコマンドは、選択できる使用可能なテンプレートのセットを表示します。

Databricks は、次のデフォルトのバンドル テンプレートを提供します。

テンプレート

説明

default-python

Databricks で Python を使用するためのテンプレート。 このテンプレートは、ジョブとDelta Live Tablesパイプラインのバンドルを作成します。 「それでもPythonを参照してください。

default-sql

Databricks で SQL を使用するためのテンプレート。 このテンプレートには、SQL ウェアハウスで SQL クエリを実行するジョブを定義する構成ファイルが含まれています。 大丈夫-sql を参照してください。

dbt-sql

ローカル開発に dbt-core を活用し、デプロイにバンドルするテンプレート。 このテンプレートには、dbt タスクを含むジョブを定義する構成と、デプロイされた dbt ジョブの dbt プロファイルを定義する構成ファイルが含まれています。 dbt-sqlを参照してください。

mlops-stacks

新しい MLOps スタック プロジェクトを開始するための高度なフルスタック テンプレート。 MLOps スタックのmlops-stacksおよびDatabricks アセット バンドルを参照してください。

カスタムバンドルテンプレートを使用する

Databricks のデフォルト バンドル テンプレート以外のバンドル テンプレートを使用するには、テンプレートのローカル パスまたはリモート URL をDatabricks CLI bundle initコマンドに渡します。

たとえば、次のコマンドは、 「カスタム バンドル テンプレートのチュートリアル」で作成されたdab-container-templateテンプレートを使用します。

   databricks bundle init /projects/my-custom-bundle-templates/dab-container-template

バンドルテンプレートの作成

バンドルテンプレートは、Go パッケージテンプレート構文を使用します。 Go パッケージテンプレート のドキュメントを参照してください。

バンドル・テンプレート・プロジェクトには、少なくとも次のものが必要です。

  • プロジェクト・ルートにある databricks_template_schema.json ・ファイルで、バンドル・プロジェクト名に対して 1 つのユーザー・プロンプト変数を定義します。

  • template フォルダにあるdatabricks.yml.tmplファイルで、テンプレートを使用して作成されたバンドルの設定を定義します。databricks.yml.tmplファイルが追加の*.yml.tmpl構成テンプレートを参照している場合は、includeマッピングでこれらの場所を指定します。

オプションで、テンプレートによって作成されたバンドルにミラーリングするサブフォルダとファイルを template フォルダに追加できます。

ユーザー・プロンプト変数の定義

基本的なバンドル テンプレートを構築する最初のステップは、プロジェクト ルートにテンプレート プロジェクト フォルダーとdatabricks_template_schema.jsonという名前のファイルを作成することです。 このファイルには、ユーザーがテンプレートを使用して bundle initを使用してバンドルを作成するときに入力値を指定する変数が含まれています。 このファイルの形式は、 JSON スキーマ仕様に従っています。

mkdir basic-bundle-template
touch basic-bundle-template/databricks_template_schema.json

databricks_template_schema.json ファイルに次の内容を追加し、ファイルを保存します。

{
   "properties": {
   "project_name": {
      "type": "string",
      "default": "basic_bundle",
      "description": "What is the name of the bundle you want to create?",
      "order": 1
   }
   },
   "success_message": "\nYour bundle '{{.project_name}}' has been created."
}

このファイルの内容:

  • project_name は唯一の入力変数名です。

  • default ユーザーがbundle initコマンドの一部として--config-fileを使用して値を指定しなかった場合、またはコマンド プロンプトでユーザーがオーバーライドした場合の、オプションのデフォルト値です。

  • description ユーザーがbundle initコマンドの一部として--config-fileを使用して値を指定しなかった場合、入力変数に関連付けられたユーザー プロンプトです。

  • order これは、ユーザーがbundle initコマンドの一部として--config-fileを使用して値を指定しなかった場合に、各ユーザー プロンプトが表示されるオプションの順序です。 orderを指定しない場合、ユーザー・プロンプトはスキーマにリストされている順序で表示されます。

  • success_message は、プロジェクトが正常に作成されたときに表示されるオプションのメッセージです。

フォルダー構造を構築する

次に、必要な template フォルダを作成し、その中にフォルダ構造を構築します。 この構造は、このテンプレートで作成されたバンドルによってミラーリングされます。 また、これらのフォルダーに含めるファイルをすべて配置します。 この基本的なバンドル テンプレートは、ファイルをsrcフォルダーに保存し、1 つの単純なノートブックを含みます。

mkdir -p basic-bundle-template/template/src
touch basic-bundle-template/template/src/simple_notebook.ipynb

simple_notebook.ipynb ファイルに以下を追加します。

print("Hello World!")

構成テンプレート・ファイルへの入力

次に、必要な databricks.yml.tmpl ファイルを template フォルダーに作成します。

touch basic-bundle-template/template/databricks.yml.tmpl

このファイルに基本構成テンプレート YAML を入力します。 この構成テンプレートは、バンドル名、指定されたノートブック ファイルを使用する 1 つのジョブ、およびこのテンプレートを使用して作成されたバンドルの 2 つのターゲット環境を確立します。 また、バンドル置換も利用しており、これを強くお勧めします。 バンドル置換 (bundle substitutions) を参照。

# This is the configuration for the Databricks Asset Bundle {{.project_name}}.

bundle:
  name: {{.project_name}}

# The main job for {{.project_name}}
resources:
    jobs:
        {{.project_name}}_job:
        name: {{.project_name}}_job
        tasks:
            - task_key: notebook_task
            job_cluster_key: job_cluster
            notebook_task:
                notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
            new_cluster:
                node_type_id: i3.xlarge
                spark_version: 13.3.x-scala2.12

targets:
  # The deployment targets. See https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html
  dev:
    mode: development
    default: true
    workspace:
      host: {{workspace_host}}

  prod:
    mode: production
    workspace:
      host: {{workspace_host}}
      root_path: /Shared/.bundle/prod/${bundle.name}
    {{- if not is_service_principal}}
    run_as:
      # This runs as {{user_name}} in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: {{user_name}}
    {{end -}}

バンドルテンプレートをテストする

最後に、テンプレートをテストします。 新しいバンドル プロジェクト フォルダーを作成し、Databricks CLI を使用して、テンプレートを使用して新しいバンドルを初期化します。

mkdir my-test-bundle
cd my-test-bundle
databricks bundle init ../basic-bundle-template

プロンプト What is your bundle project name?に my_test_bundleと入力します。

テストバンドルが作成されると、スキーマファイルから成功メッセージが出力されます。 my-test-bundle フォルダーの内容を調べると、次のように表示されます。

my-test-bundle
   ├── databricks.yml
   └── src
      └── simple_notebook.ipynb

これで、databricks.ymlファイルがカスタマイズされました。

# This is the configuration for the Databricks Asset Bundle my-test-bundle.

bundle:
  name: my-test-bundle

# The main job for my-test-bundle
resources:
    jobs:
        my-test-bundle_job:
        name: my-test-bundle_job
        tasks:
            - task_key: notebook_task
                job_cluster_key: job_cluster
                notebook_task:
                    notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
                new_cluster:
                    node_type_id: i3.xlarge
                    spark_version: 13.3.x-scala2.12

targets:
  # The 'dev' target, used for development purposes. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#development-mode)
  dev:
    mode: development
    default: true
    workspace:
      host: https://my-host.cloud.databricks.com

  # The 'prod' target, used for production deployment. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#production-mode)
  prod:
    mode: production
    workspace:
      host: https://my-host.cloud.databricks.com
      root_path: /Shared/.bundle/prod/${bundle.name}
    run_as:
      # This runs as someone@example.com in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: someone@example.com

テンプレートを共有する

このバンドルテンプレートを他のユーザーと共有する場合は、Git がサポートし、ユーザーがアクセスできる任意のプロバイダーのバージョン管理に保存できます。 Git URL を使用して bundle init コマンドを実行するには、 databricks_template_schema.json ファイルがその Git URL からの相対ルートの場所にあることを確認します。

ヒント

databricks_template_schema.json ファイルは、バンドルのルートに対して相対的な別のフォルダに配置できます。次に、 bundle init コマンドの --template-dir オプションを使用して、 databricks_template_schema.json ファイルを含むそのフォルダーを参照できます。

次のステップ