宣言型オートメーション バンドル プロジェクト テンプレート

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

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

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

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 のマッピングでそれらの場所を指定します。 構成テンプレートを参照してください。

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

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

テンプレート スキーマ

カスタム バンドル テンプレート プロジェクトには、プロジェクト ルートに databricks_template_schema.jsonJSON ファイル が含まれている必要があります。 このファイルは、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}}など) を使用してアクセスできます。

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

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

構成テンプレート

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

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

template/{{.project_name}}/databricks.yml.tmpl:

# databricks.yml
# This is the configuration for the 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 -}}

template/{{.project_name}}/resources/{{.project_name}}_job.yml.tmpl:

# {{.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 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 を基準としたルートの場所にあることを確認してください。

ワークスペースでカスタム テンプレート フォルダーを構成する

カスタム バンドル テンプレートは、ワークスペースでバンドルを作成するために使用できます。

1. バンドル テンプレートをGitHub リポジトリに格納し、それに接続するように Git フォルダーを構成します。 Git フォルダーの構成の詳細については、「 リポジトリの複製」を参照してください。

2. アカウントまたはワークスペース管理者として、ワークスペースの [設定] に移動します。 「ワークスペースを管理する」を参照してください。

3. [ 開発] をクリックします。

4. [ 宣言型オートメーション バンドル] で、カスタム テンプレートのフォルダーを選択します。 すべてのカスタム バンドル テンプレートは、フォルダーのルート レベルで使用できる必要があります。

   

5. アクセス許可ダイアログが表示されたら、すべてのユーザーにカスタム テンプレートのフォルダーへのアクセスを表示できるようにします。または、[アクセス権を 付与しない ] を選択して、より詳細なアクセス許可を設定します。

   1. より詳細なアクセス許可を設定するには、任意のフォルダー内の 3 つのドットを選択し、[ 詳細の表示] をクリックします。

      

   2. Git フォルダーの詳細パネルで [共有] をクリックします。

   3. テンプレートを編集できるユーザー (CAN MANAGE) と、テンプレートを使用してバンドルを作成できるユーザー (CAN VIEW) を選択します。

   アクセス許可の詳細については、「 フォルダー ACL とGit フォルダー ACL」を参照してください。

ワークスペースでバンドルを作成するときに、このフォルダー内のテンプレートをユーザーが使用できるようになりました。 「バンドルの作成」を参照してください。

次のステップ

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