次の方法で共有

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

  • [アーティクル]

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

バンドル テンプレートを使うと、ユーザーは、開発環境のデプロイ パイプライン全体で共通するフォルダー構造、構築の手順とタスク、テスト、その他の DevOps のコードとしてのインフラストラクチャ (IaC) 属性を確立して、一貫性があり繰り返すのことのできる方法でバンドルを作成できます。

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

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

テンプレートに基づいてバンドルを作成する

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

既定のバンドル テンプレートを使用する

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

databricks bundle init default-python

既定のテンプレートを指定しないと、bundle init コマンドはユーザーが選んで使用できるテンプレートのセットを表示します。

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

Template 説明
default-python Databricks で Python を使うためのテンプレート。 このテンプレートでは、ジョブと Delta Live Tables パイプラインを含むバンドルが作成されます。 default-python を参照してください。
default-sql Databricks で SQL を使うためのテンプレート。 このテンプレートには、SQL ウェアハウスで SQL クエリを実行するジョブを定義する構成ファイルが含まれています。 default-sql を参照してください。
dbt-sql ローカル開発用に dbt-core を利用し、デプロイ用にバンドルを使うテンプレート。 このテンプレートには、dbt タスクを含むジョブを定義する構成と、デプロイされる dbt ジョブの dbt プロファイルを定義する構成ファイルが含まれています。 dbt-sql を参照してください。
mlops-stacks 新しい MLOps スタック プロジェクトを開始するための高度なフル スタック テンプレート。 mlops-stacks と、「MLOps スタック用の Databricks アセット バンドル」をご覧ください。.

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

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

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

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

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

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

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

  • バンドル プロジェクト名に対する 1 つのユーザー プロンプト変数が定義されている、プロジェクト ルートの databricks_template_schema.json ファイル。
  • テンプレートで作成されるバンドルの構成が定義されている、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!")

構成テンプレート ファイルを設定する

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

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

このファイルに、基本的な構成テンプレート YAML を設定します。 この構成テンプレートは、バンドル名、指定されたノートブック ファイルを使う 1 つのジョブ、このテンプレートを使って作成されるバンドル用の 2 つのターゲット環境を設定します。 また、バンドルの置換も利用します。これは強くお勧めします。 バンドルの置換に関する記事をご覧ください。

# 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 ファイルが含まれるそのフォルダーを参照できます。

次のステップ