Databricks アセット バンドル プロジェクト テンプレート

Databricks アセット バンドルでは、ジョブ、パイプライン、ノートブックなどの Databricks リソースをソース ファイルとして記述し、これらのソース ファイルと共にメタデータを含め、インフラストラクチャやその他のリソースをプロビジョニングし、プロジェクトのエンドツーエンドの定義を提供できます。これらはすべて単一の配置可能なプロジェクトとしてパッケージ化されています。 「Databricks アセット バンドルとは」をご覧ください。

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

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

Databricks には、既定のバンドル テンプレートのセットが用意されていますが、カスタム バンドル テンプレート作成することもできます。 ユーザーは、既定のテンプレートまたはカスタム テンプレートを指定して、bundle init コマンドを使用してバンドルを初期化できます。

テンプレートを使用してバンドルを作成する

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

databricks bundle init default-python

カスタム バンドル テンプレートを使用するには、テンプレートのローカル パスまたはリモート URL を Databricks CLIbundle init コマンドに渡します。

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

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

テンプレートを指定しない場合、bundle init コマンドは、選択できる一連の使用可能な既定のテンプレートと共にプロンプトを表示します。

既定のバンドル テンプレート

Azure Databricks では、次の既定のバンドル テンプレートが提供されています。

カスタム バンドル テンプレート

バンドル テンプレートでは Go パッケージ テンプレート構文が使用されます。この構文により、作成できるカスタム バンドル テンプレートに柔軟性が提供されます。 Go パッケージ テンプレートのドキュメントを参照してください。

テンプレート プロジェクトの構造

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

• バンドル プロジェクト名の 1 つのユーザー プロンプト プロパティを定義するプロジェクト ルートの databricks_template_schema.json ファイル。 テンプレート スキーマ 参照してください。
• テンプレートで作成されるバンドルの構成が定義されている、databricks.yml.tmpl フォルダーの template ファイル。 databricks.yml.tmpl ファイルで追加の *.yml.tmpl 構成テンプレートが参照されている場合は、include のマッピングでそれらの場所を指定します。 YML 構成テンプレート を参照してください。

さらに、バンドル テンプレート プロジェクト template フォルダーのフォルダー構造とインクルード ファイルは、テンプレートで作成されたバンドルによってミラー化されます。 たとえば、テンプレートで、src フォルダー内の単純なノートブックと、resources フォルダー内のノートブックを実行するジョブ定義を含むバンドルを生成する場合は、次のようにテンプレート プロジェクトを整理します。

basic-bundle-template
  ├── databricks_template_schema.json
  └── template
      ├── databricks.yml.tmpl
      ├── resources
      │   └── {{.project_name}}_job.yml.tmpl
      └── src
          └── simple_notebook.ipynb

テンプレート スキーマ

カスタム バンドル テンプレート プロジェクトには、プロジェクト ルートにhttps://json-schema.org/specification.htmldatabricks_template_schema.json [JSON ファイル]( が含まれている必要があります。 このファイルは、bundle init コマンドの実行時に Databricks CLI によって使用されるフィールド (プロンプト テキストなど) を定義します。

次の基本的な databricks_template_schema.json ファイルは、プロンプト メッセージと既定値を含む、バンドル プロジェクトの入力変数 project_name を定義します。 次に、メッセージ内の入力変数値を使用する、バンドル プロジェクト初期化のための成功メッセージを定義します。

{
  "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."
}

テンプレート スキーマ フィールド

databricks_template_schema.json ファイルでは、properties フィールド内のユーザーからのバンドル初期化中に情報を収集するための入力変数と、初期化をカスタマイズするための追加フィールドの定義がサポートされています。

入力変数は、テンプレート スキーマの properties フィールドで定義されます。 各入力変数は、バンドルの初期化中にユーザーにプロンプトを表示するために必要なメタデータを定義します。 変数の値には、テンプレート変数の構文 ({{.project_name}}など) を使用してアクセスできます。

一部のフィールドの値を設定して、バンドル初期化プロセスをカスタマイズすることもできます。

サポートされているスキーマ フィールドを次の表に示します。

YML 構成テンプレート

カスタム バンドル テンプレートには、バンドル プロジェクト databricks.ymlの作成に使用されるバンドル テンプレート プロジェクトの template フォルダーに、databricks.yml.tmpl ファイルが含まれている必要があります。 このテンプレート ファイルに基本的な構成テンプレート YAML を設定します。

次のdatabricks.ymlおよび関連付けられている *_job.yml の構成テンプレートの例では、バンドル名と 2 つのターゲット環境を確立し、このテンプレートを使用して作成されたバンドルに対して、バンドル内でノートブックを実行するジョブを定義します。 これらの構成テンプレートでは、バンドルの置換とバンドル テンプレート ヘルパーを利用します。 バンドルの置換 およびバンドル テンプレート ヘルパーを参照してください。

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

bundle:
  name: {{.project_name}}

include:
  - resources/*.yml

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 -}}

# {{.project_name}}_job.yml
# 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

テンプレート ヘルパーと変数

テンプレート ヘルパーは Databricks によって提供される関数で、実行時にユーザー固有の情報を取得したり、テンプレート エンジンと対話したりするためにテンプレート ファイル内で使用できます。 独自のテンプレート変数を定義することもできます。

Databricks バンドル テンプレート プロジェクトでは、次のテンプレート ヘルパーを使用できます。 Go テンプレートと変数の使用については、「Go テンプレート を参照してください。

独自の変数を定義するには、テンプレート プロジェクトの library フォルダーにテンプレート ファイルを作成し、Go テンプレート構文を使用して変数を定義します。 たとえば、library/variables.tmpl ファイルの次の内容は、変数の cli_version と model_nameを定義します。 このテンプレートを使用してバンドルを初期化する場合、model_name 変数の値は、テンプレート スキーマ ファイルで定義されている input_project_name フィールドを使用して構築されます。 このフィールド値の値は、プロンプトの後のユーザー入力です。

{{ define `cli_version` -}}
    v0.240.0
{{- end }}

{{ define `model_name` -}}
    {{ .input_project_name }}-model
{{- end }}

完全な例については、mlops-stacks テンプレート変数ファイル を参照してください。

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

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

databricks bundle init basic-bundle-template

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

テスト バンドルが作成されると、スキーマ ファイルからの成功メッセージが出力されます。 my_test_bundle フォルダーの内容を調べると、次のようになっているはずです。

my_test_bundle
   ├── databricks.yml
   ├── resources
   │  └── my_test_bundle_job.yml
   └── src
      └── simple_notebook.ipynb

databricks.ymlファイルとジョブがカスタマイズされました。

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

bundle:
  name: my_test_bundle

include:
  - resources/*.yml

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

# my_test_bundle_job.yml
# 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

テンプレートを共有する

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

次のステップ

• Databricks によって作成され、保守管理されている追加のテンプレートを参照します。 GitHub のバンドル サンプル リポジトリをご覧ください。
• Databricks アセット バンドル テンプレートで MLOps スタックを使うには、「MLOps スタック用の Databricks アセット バンドル」を参照してください。
• Go パッケージのテンプレートについて詳しくは、こちらをご覧ください。 Go パッケージ テンプレートのドキュメントを参照してください。