Databricks アセット バンドルの構成

この記事では、Databricksアセットバンドルを定義するDatabricksアセットバンドルの構成ファイルの構文について説明します。「Databricksアセットバンドルとは？」を参照してください。

バンドルを作成して操作するには、「 Databricks アセット バンドルの開発」を参照してください。

概要

バンドル構成ファイルはYAML形式で表現する必要があり、少なくとも最上位のバンドルマッピングが含まれている必要があります。各バンドルには、databricks.ymlという名前のバンドル構成ファイルが少なくとも1つ（そして1つだけ）含まれている必要があります。バンドル構成ファイルが複数ある場合は、includeマッピングを使用してdatabricks.ymlファイルで参照する必要があります。

各トップレベルマッピングの詳細については、 マッピングを参照してください。

YAMLの詳細については、公式のYAMLの仕様とチュートリアルを参照してください。

仕様

次の YAML 仕様では、Databricks アセット バンドルの最上位の構成キーが提供されています。 構成のリファレンスについては、 構成のリファレンスを参照してください。

# This is the default bundle configuration if not otherwise overridden in
# the "targets" top-level mapping.
bundle: # Required.
  name: string # Required.
  databricks_cli_version: string
  cluster_id: string
  git:
    origin_url: string
    branch: string

# These are for any custom variables for use throughout the bundle.
variables:
  <some-unique-variable-name>:
    description: string
    default: string or complex

# These are the default workspace settings if not otherwise overridden in
# the following "targets" top-level mapping.
workspace:
  artifact_path: string
  auth_type: string
  azure_client_id: string # For Azure Databricks only.
  azure_environment: string # For Azure Databricks only.
  azure_login_app_id: string # For Azure Databricks only. Non-operational and reserved for future use.
  azure_tenant_id: string # For Azure Databricks only.
  azure_use_msi: true | false # For Azure Databricks only.
  azure_workspace_resource_id: string # For Azure Databricks only.
  client_id: string # For Databricks on AWS only.
  file_path: string
  google_service_account: string # For Databricks on Google Cloud only.
  host: string
  profile: string
  root_path: string
  state_path: string

# These are the permissions to apply to experiments, jobs, models, and pipelines defined
# in the "resources" mapping.
permissions:
  - level: <permission-level>
    group_name: <unique-group-name>
  - level: <permission-level>
    user_name: <unique-user-name>
  - level: <permission-level>
    service_principal_name: <unique-principal-name>

# These are the default artifact settings if not otherwise overridden in
# the following "targets" top-level mapping.
artifacts:
  <some-unique-artifact-identifier>:
    build: string
    files:
      - source: string
    path: string
    type: string

# These are any additional configuration files to include.
include:
  - "<some-file-or-path-glob-to-include>"
  - "<another-file-or-path-glob-to-include>"

# This is the identity to use to run the bundle
run_as:
  - user_name: <user-name>
  - service_principal_name: <service-principal-name>

# These are the default job and pipeline settings if not otherwise overridden in
# the following "targets" top-level mapping.
resources:
  clusters:
    <some-unique-programmatic-identifier-for-this-cluster>:
      # See the REST API create request payload reference for clusters.
  dashboards:
    <some-unique-programmatic-identifier-for-this-dashboard>:
      # See the REST API create request payload reference for dashboards.
  experiments:
    <some-unique-programmatic-identifier-for-this-experiment>:
      # See the REST API create request payload reference for experiments.
  jobs:
    <some-unique-programmatic-identifier-for-this-job>:
      # See REST API create request payload reference for jobs.
  models:
    <some-unique-programmatic-identifier-for-this-model>:
      # See the REST API create request payload reference for models.
  pipelines:
    <some-unique-programmatic-identifier-for-this-pipeline>:
      # See the REST API create request payload reference for Delta Live Tables (pipelines).
  schemas:
    <some-unique-programmatic-identifier-for-this-schema>:
      # See the Unity Catalog schema request payload reference.
  volumes:
    <some-unique-programmatic-identifier-for-this-volume>:
    # See the Unity Catalog volume request payload reference.


# These are any additional files or paths to include or exclude.
sync:
  include:
    - "<some-file-or-path-glob-to-include>"
    - "<another-file-or-path-glob-to-include>"
  exclude:
    - "<some-file-or-path-glob-to-exclude>"
    - "<another-file-or-path-glob-to-exclude>"
  paths:
    - "<some-file-or-path-to-synchronize>"

# These are the targets to use for deployments and workflow runs. One and only one of these
# targets can be set to "default: true".
targets:
  <some-unique-programmatic-identifier-for-this-target>:
    artifacts:
      # See the preceding "artifacts" syntax.
    bundle:
      # See the preceding "bundle" syntax.
    cluster_id: string
    default: true | false
    mode: development
    presets:
      <preset>: <value>
    resources:
      # See the preceding "resources" syntax.
    sync:
      # See the preceding "sync" syntax.
    variables:
      <preceding-unique-variable-name>: <non-default-value>
    workspace:
      # See the preceding "workspace" syntax.
    run_as:
      # See the preceding "run_as" syntax.

例：

注：

バンドルの機能と一般的なバンドルの使用例を示す構成例については、「バンドル構成の例」と「GitHubのバンドル例リポジトリ」を参照してください。

次のバンドル構成の例では、databricks.ymlという名前のローカルバンドル構成ファイルと同じディレクトリにあるhello.pyという名前のローカルファイルを指定しています。これは、指定されたクラスターIDのリモートクラスターを使用して、このノートブックをジョブとして実行します。リモートワークスペースのURLとワークスペース資格情報は、DEFAULTという名前の呼び出し元のローカル構成プロファイルから読み取られます。

Databricksでは、可能な限りdefaultマッピングの代わりにhostマッピングを使用して、バンドル構成ファイルの移植性を向上させることをお勧めします。hostマッピングを設定すると、Databricks CLIは.databrickscfgファイル内で一致するプロファイルを検索し、そのプロファイルのフィールドを使用して、使用するDatabricks認証タイプを決定します。.databrickscfgファイル内に一致するhostフィールドを持つ複数のプロファイルが存在する場合は、profileを使用して、使用する特定のプロファイルをDatabricks CLIに指示する必要があります。例については、このセクションの後半のprodターゲット宣言を参照してください。

この手法により、次のように、resourcesブロック内のジョブ定義と設定を再利用したり、上書きしたりすることができます。

bundle:
  name: hello-bundle

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

targets:
  dev:
    default: true

次のバンドル構成ファイルは機能的には同等ですが、モジュール化されていないため、再利用が困難です。また、この宣言は既存のジョブを上書きするのではなく、ジョブにタスクを追加します。

bundle:
  name: hello-bundle

targets:
  dev:
    default: true
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 1234-567890-abcde123
              notebook_task:
                notebook_path: ./hello.py

次の例では、異なるリモートワークスペースのURLとワークスペース認証資格情報を使用するprodという名前のターゲットを追加します。これらの資格情報は、指定されたワークスペースURLを持つ呼び出し元の.databrickscfgファイルと一致するhostエントリから読み取られます。このジョブは同じノートブックを実行しますが、指定されたクラスターIDを持つ別のリモートクラスターを使用します。prodマッピング内でnotebook_taskマッピングを宣言する必要はないことに注意してください。これは、notebook_taskマッピングがprodマッピング内で明示的にオーバーライドされていない場合、最上位のresourcesマッピング内でnotebook_taskマッピングを使用するようフォールバックされるためです。

bundle:
  name: hello-bundle

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

devターゲット内でこのジョブを検証、デプロイ、実行するには、次のようにします。

# Because the "dev" target is set to "default: true",
# you do not need to specify "-t dev":
databricks bundle validate
databricks bundle deploy
databricks bundle run hello_job

# But you can still explicitly specify it, if you want or need to:
databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev hello_job

代わりに、prodターゲット内でこのジョブを検証、デプロイ、実行するには、次のようにします。

# You must specify "-t prod", because the "dev" target
# is already set to "default: true":
databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod hello_job

次の例は前の例をコンポーネントファイルに分割してさらにモジュール化し、複数のバンドル構成ファイル間で再利用しやすくしています。この手法により、さまざまな定義や設定を再利用できるだけでなく、これらのファイルのいずれかを、まったく異なる宣言を提供する他のファイルと交換することもできます。

databricks.yml:

bundle:
  name: hello-bundle

include:
  - "bundle*.yml"

bundle.resources.yml:

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

bundle.targets.yml:

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

マッピング

次のセクションでは、バンドル構成ファイルの構文をトップレベルのマッピングごとに説明します。

バンドル

バンドル構成ファイルには、バンドルのコンテンツとDatabricksワークスペース設定を関連付ける最上位のbundleマッピングが1つだけ含まれている必要があります。

このbundleマッピングには、バンドルのプログラム名（または論理名）を指定するnameマッピングを含める必要があります。次の例では、プログラム名（または論理名）hello-bundleを持つバンドルを宣言しています。

bundle:
  name: hello-bundle

bundleマッピングは、最上位レベルのターゲットマッピングの1つ以上のターゲットの子にすることもできます。これらの子bundleマッピングはそれぞれ、ターゲットレベルでのデフォルト以外のオーバーライドを指定します。ただし、最上位レベルのbundleマッピングのname値はターゲットレベルでオーバーライドできません。

クラスタリング

bundleマッピングは、マッピングcluster_id子を持つことができます。このマッピングにより、バンドル構成ファイル内の他の場所で定義されているクラスターのオーバーライドとして使用するクラスターの ID を指定できます。 クラスターの ID を取得する方法については、「 クラスターの URL と ID」を参照してください。

cluster_idオーバーライドは開発のみのシナリオを対象としており、modeマッピングが developmentに設定されているターゲットでのみサポートされます。targetマッピングの詳細については、「ターゲット」を参照してください。

compute_id

注：

この設定は非推奨です。 代わりに クラスタリング を使用してください。

bundleマッピングは、マッピングcompute_id子を持つことができます。このマッピングにより、バンドル構成ファイル内の他の場所で定義されているクラスターのオーバーライドとして使用するクラスターの ID を指定できます。

git

バンドルに関連付けられたGitバージョン管理の詳細を取得し、上書きすることができます。これは、デプロイされたリソースに注釈を付けるのに役立ちます。たとえば、デプロイする機械学習モデルの説明に、リポジトリの元のURLを含めたい場合などです。

validate、deploy、runなどのbundleコマンドを実行すると、bundleコマンドによってコマンドの構成ツリーに以下のデフォルト設定が入力されます。

• bundle.git.origin_urlこれは、リポジトリの配信元 URL を表します。 これは、クローン作成されたリポジトリからコマンド git config --get remote.origin.url を実行した場合に取得する値と同じです。 置換を使用して、バンドル設定ファイルでこの値を参照できます (${bundle.git.origin_url})。

• bundle.git.branchこれは、リポジトリ内の現在のブランチを表します。 これは、クローン作成されたリポジトリからコマンド git branch --show-current を実行した場合に取得する値と同じです。 置換を使用して、バンドル設定ファイルでこの値を参照できます (${bundle.git.branch})。

Git設定を取得または上書きするには、バンドルがGitリポジトリに関連するディレクトリ、たとえばgit cloneコマンドを実行して初期化されたローカルディレクトリ内にある必要があります。ディレクトリがGitリポジトリに関連付けられていない場合、これらのGit設定は空になります。

必要に応じて、次のように、最上位のbundleマッピングのgitマッピング内のorigin_urlとbranchの設定を上書きできます。

bundle:
  git:
    origin_url: <some-non-default-origin-url>
    branch: <some-non-current-branch-name>

databricks_cli_version

bundleマッピングには、バンドルに必要なDatabricks CLIバージョンを制限するdatabricks_cli_versionマッピングを含めることができます。これにより、特定のバージョンのDatabricks CLIでサポートされていないマッピングを使用することによって発生する問題を防ぐことができます。

Databricks CLIバージョンはセマンティックバージョン管理に準拠しており、databricks_cli_versionマッピングはバージョン制約の指定をサポートしています。現在のdatabricks --version値がバンドルのdatabricks_cli_versionマッピングで指定された範囲内にない場合、バンドルでdatabricks bundle validateを実行するとエラーが発生します。次の例は、一般的なバージョン制約の構文を示しています。

bundle:
  name: hello-bundle
  databricks_cli_version: "0.218.0" # require Databricks CLI 0.218.0

bundle:
  name: hello-bundle
  databricks_cli_version: "0.218.*" # allow all patch versions of Databricks CLI 0.218

bundle:
  name: my-bundle
  databricks_cli_version: ">= 0.218.0" # allow any version of Databricks CLI 0.218.0 or higher

bundle:
  name: my-bundle
  databricks_cli_version: ">= 0.218.0, <= 1.0.0" # allow any Databricks CLI version between 0.218.0 and 1.0.0, inclusive

変数

bundles 設定ファイルには、カスタム変数が定義されている最上位の variables マッピングを 1 つ含めることができます。 変数ごとに、次の形式を使用して、オプションの説明、デフォルト値、カスタム変数が複合型であるかどうか、または ID 値を取得するためのルックアップを設定します。

variables:
  <variable-name>:
    description: <variable-description>
    default: <optional-default-value>
    type: <optional-type-value> # "complex" is the only valid value
    lookup:
      <optional-object-type>: <optional-object-name>

注：

typeがcomplexに設定されていない限り、変数はstringタイプであると見なされます。「複素変数を定義する」を参照してください。

バンドル設定内でカスタム変数を参照するには、置換 ${var.<variable_name>}を使用します。

カスタム変数と置換の詳細については、「Databricks アセットバンドルの置換と変数」を参照してください。

ワークスペース

バンドル構成ファイルには、使用するデフォルト以外のDatabricksワークスペース設定を指定するための最上位のworkspaceマッピングを1つだけ含めることができます。

重要

有効な Databricks ワークスペース パスは、 /Workspace または /Volumesで始まります。 カスタムワークスペースパスには、自動的に /Workspaceというプレフィックスが付けられるので、カスタムパスでワークスペースパスの置換 ( ${workspace.file_path}など) を使用する場合、パスの先頭に /Workspace を付ける必要はありません。

root_path

このworkspaceマッピングにはroot_pathマッピングを含めることができます。これにより、デプロイメントとワークフロー実行の両方で、ワークスペース内で使用するデフォルト以外のルートパスを指定できます。次に例を示します。

workspace:
  root_path: /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

デフォルトでは、 root_pathの場合、Databricks CLIは置換を使用する/Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}のデフォルトパスを使用します。

artifact_path

このworkspaceマッピングにはartifact_pathマッピングを含めることもできます。これにより、デプロイメントとワークフロー実行の両方で、ワークスペース内で使用するデフォルト以外のアーティファクトパスを指定できます。次に例を示します。

workspace:
  artifact_path: /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/artifacts

デフォルトでは、 artifact_pathの場合、Databricks CLIは置換を使用する${workspace.root}/artifactsのデフォルトパスを使用します。

注：

artifact_pathマッピングはDatabricksファイルシステム（DBFS）パスをサポートしていません。

ファイルパス

このworkspaceマッピングにはfile_pathマッピングを含めることもできます。これにより、デプロイメントとワークフロー実行の両方で、ワークスペース内で使用するデフォルト以外のファイルパスを指定できます。次に例を示します。

workspace:
  file_path: /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/files

デフォルトでは、 file_pathの場合、Databricks CLIは置換を使用する${workspace.root}/filesのデフォルトパスを使用します。

state_path

state_pathマッピングはデフォルトで${workspace.root}/stateのデフォルトパスに設定され、デプロイメントに関するTerraformの状態情報を格納するためのワークスペース内のパスを表します。

その他のワークスペースマッピング

workspaceマッピングには、使用するDatabricks認証メカニズムを指定するための次のオプションのマッピングを含めることもできます。このworkspace・マッピングで指定されていない場合は、最上位レベルのターゲットマッピングの1つ以上のターゲットの子としてworkspaceマッピングで指定する必要があります。

重要

Databricks認証の次のworkspaceマッピングの値をハードコードする必要があります。たとえば、${var.*}構文を使用して、これらのマッピングの値にカスタム変数を指定することはできません。

• profileマッピング（または、Databricks CLIを使用してバンドルの検証、デプロイ、実行、および破棄コマンドを実行する場合の--profileまたは-pオプション）は、このワークスペースでDatabricks認証に使用する構成プロファイルの名前を指定します。この構成プロファイルは、Databricks CLIをセットアップしたときに作成した構成プロファイルにマップされます。

  注：

  Databricksでは、バンドル構成ファイルの移植性を向上させるために、profileマッピングではなく、hostマッピング（または、Databricks CLIを使用してバンドルの検証、デプロイ、実行、および破棄コマンドを実行するときの--profileまたは-pオプション）を使用することを推奨しています。hostマッピングを設定すると、Databricks CLIは.databrickscfgファイル内で一致するプロファイルを検索し、そのプロファイルのフィールドを使用して、使用するDatabricks認証タイプを決定します。.databrickscfgファイル内に、一致するhostフィールドを持つ複数のプロファイルが存在する場合は、profileマッピング（または--profileまたは-pコマンドラインオプション）を使用して、使用するプロファイルをDatabricks CLIに指示する必要があります。例については、例のprodターゲット宣言を参照してください。

• hostマッピングは、DatabricksワークスペースのURLを指定します。「ワークスペースインスタンス名、URL、ID」を参照してください。

• OAuth マシン間 (M2M) 認証の場合は、 client_id マッピングを使用します。 または、ローカル環境変数 DATABRICKS_CLIENT_IDでこの値を設定することもできます。 または、 client_id 値を使用して構成プロファイルを作成し、 profile マッピングでプロファイルの名前を指定できます (または Databricks CLI でバンドルの検証、デプロイ、実行、破棄コマンドを実行するときに --profile または -p オプションを使用します)。 「 Databricksを使用してサービスプリンシパルで へのアクセスを認証するOAuth (OAuth M2M)」 を参照してください。

  注：

  バンドル構成ファイルにDatabricks OAuthシークレット値を指定することはできません。代わりにローカル環境変数DATABRICKS_CLIENT_SECRETを設定します。あるいは、client_secret値を構成プロファイルに追加し、profileマッピングでプロファイル名を指定することもできます (または、Databricks CLIでバンドルの検証、デプロイ、実行、破棄コマンドを実行する際に--profileまたは-pオプションを使用します)。

• Google Cloudサービスのアカウント認証にはgoogle_service_accountマッピングが使われます。あるいは、ローカル環境変数DATABRICKS_GOOGLE_SERVICE_ACCOUNTでこの値を設定することもできます。または、google_service_account値で設定プロファイルを作成し、profileマッピングでプロファイル名を指定します (あるいは、Databricks CLIでバンドルの検証、デプロイ、実行、破棄コマンドを実行する際に--profileまたは-pオプションを使用します)。Google Cloud ID認証をご覧ください。

• auth_typeマッピングは、特にDatabricks CLIが予期しない認証タイプを推測する場合に使用するDatabricks認証タイプを指定します。「Databricks リソースへのアクセスを認証する」を参照してください。

権限

最上位のpermissionsマッピングは、バンドルで定義されているすべてのリソースに適用する1つ以上の権限レベルを指定します。特定のリソースに権限を適用する場合は、「特定のリソースに対する権限を定義する」を参照してください。

許可される最上位の権限レベルはCAN_VIEW、CAN_MANAGE、およびCAN_RUNです。

次のバンドル構成ファイルの例では、ユーザー、グループ、サービスプリンシパルの権限レベルを定義しています。これらの権限レベルは、バンドル内のresourcesで定義されているすべてのジョブ、パイプライン、エクスペリメント、モデルに適用されます。

permissions:
  - level: CAN_VIEW
    group_name: test-group
  - level: CAN_MANAGE
    user_name: someone@example.com
  - level: CAN_RUN
    service_principal_name: 123456-abcdef

アーティファクト

最上位のartifactsマッピングは、アーティファクトを1つ以上指定します。このアーティファクトはバンドルのデプロイメント時に自動的に構築され、バンドルの実行の後で使用できます。各子アーティファクトは、以下のマッピングをサポートしています。

• type が必要です。デプロイする前にPython wheelファイルをビルドするには、このマッピングをwhlに設定する必要があります。

• path バンドル構成ファイルの場所からPython wheelファイルのsetup.pyファイルの場所までのオプションの相対パスです。pathが含まれていない場合、Databricks CLIはプロジェクトのルートでPython wheelファイルのsetup.pyファイルを見つけようとします。

• files は、子sourceマッピングを含むオプションのマッピングです。これを使用して、複雑なビルド命令に含めるデフォルト以外の場所を指定できます。場所は、バンドル構成ファイルの場所からの相対パスとして指定されます。

• build は、デプロイメント前にローカルで実行するデフォルト以外のビルドコマンドのオプションセットです。Python wheelビルドの場合、Databricks CLIは、ビルドを実行するためのPython wheelパッケージのローカルインストールを見つけることができることを前提としており、各バンドルのデプロイメント中にデフォルトでコマンドpython setup.py bdist_wheelを実行します。複数のビルドコマンドを指定するには、各コマンドをダブルアンパサンド（&&）の文字で区切ります。

次の設定例では、Poetry を使用してホイールを構築します。

artifacts:
  default:
    type: whl
    build: poetry build
    path: .

を使用する完全なサンプルartifacts バンドルについては、「 アセット バンドルを使用したPython wheel ファイルの開発Databricks 」を参照してください。

ヒント

バンドル内のアーティファクトの設定を定義、結合、上書きできます (「Databricks アセットバンドルでのアーティファクト設定の定義」を参照)。

含める

include配列は、バンドル内に含める構成ファイルを含むパスglobのリストを指定します。これらのパスglobは、パスglobが指定されているバンドル構成ファイルの場所と相対するものです。

Databricks CLIは、デフォルトではバンドル内に構成ファイルは含まれません。databricks.ymlファイル自体以外の、バンドルに含めるすべての構成ファイルを指定するには、include配列を使用する必要があります。

このinclude配列は最上位のマッピングとしてのみ表示できます。

次の設定例には、3 つの設定ファイルが含まれています。 これらのファイルは、バンドル設定ファイルと同じフォルダにあります。

include:
  - "bundle.artifacts.yml"
  - "bundle.resources.yml"
  - "bundle.targets.yml"

次の設定例には、ファイル名が bundle で始まり .ymlで終わるすべてのファイルが含まれています。 これらのファイルは、バンドル設定ファイルと同じフォルダにあります。

include:
  - "bundle*.yml"

リソース

resourcesマッピングは、バンドルで使用される Databricks リソースに関する情報を指定します。

この resources ・マッピングは、最上位のマッピングとして表示することも、最上位 のターゲット ・マッピングの1つ以上のターゲットの子として表示することもでき、 サポートされているリソース・タイプが0個または1つ含まれます。 各リソース・タイプ・マッピングには、1 つ以上の個別のリソース宣言が含まれ、それぞれに一意の名前が必要です。 これらの個々のリソース宣言では、YAML で表される対応するオブジェクトの作成操作の要求ペイロードを使用して、リソースを定義します。 リソースでサポートされているプロパティは、対応するオブジェクトでサポートされているフィールドです。

作成操作リクエストのペイロードはDatabricks REST APIリファレンスに記載されており、databricks bundle schemaコマンドはサポートされているすべてのオブジェクトスキーマを出力します。さらに、databricks bundle validateコマンドは、未知のリソースプロパティがバンドル設定ファイルで見つかった場合に警告を返します。

次の設定例では、ジョブリソースを定義しています。

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

バンドルでサポートされるリソースの詳細、および一般的な設定と例については、「アセットバンドルDatabricks リソース」および「バンドル設定の例」を参照してください。

同期

syncマッピングを使用すると、バンドルデプロイメントの一部となるファイルを構成できます。

含めると除外する

syncマッピング内のincludeマッピングとexcludeマッピングでは、次のルールに従って、バンドルデプロイメントに含める、またはバンドルデプロイメントから除外するファイルまたはフォルダのリストを指定します。

• 明示的に含めるために、バンドルのルートにある.gitignoreファイル内のファイルglobとパスglobの任意のリストに基づいて、includeマッピングに、バンドルのルートに相対するファイルglob、パスglob、またはその両方のリストを含めることができます。

• 明示的に除外するために、バンドルのルートにある.gitignoreファイル内のファイルglobとパスglobのリストと、includeマッピングのファイルglobとパスglobのリストに基づいて、excludeマッピングに、バンドルのルートに相対するファイルglob、パスglob、またはその両方のリストを含めることができます。

指定されたファイルおよびフォルダへのすべてのパスは、指定されたバンドル設定ファイルのロケーションを基準にしています。

includeとexcludeのファイルパターンとパスパターンの構文は、標準の.gitignoreパターン構文に従います。「gitignoreパターンフォーマット」を参照してください。

たとえば、次の.gitignoreファイルに次のエントリが含まれているとします。

.databricks
my_package/dist

また、バンドル構成ファイルに次のincludeマッピングが含まれているとします。

sync:
  include:
    - my_package/dist/*.whl

すると、my_package/distフォルダ内のファイル拡張子が*.whlであるすべてのファイルが含まれます。my_package/distフォルダ内の他のファイルは含まれません。

ただし、バンドル構成ファイルにexcludeマッピングも含まれている場合は、次のようになります。

sync:
  include:
    - my_package/dist/*.whl
  exclude:
    - my_package/dist/delete-me.whl

すると、delete-me.whlという名前のファイルを除き、ファイル拡張子が*.whlであるmy_package/distフォルダ内のすべてのファイルが含まれます。この場合もmy_package/distフォルダ内の他のファイルは含まれません。

syncマッピングは、特定のターゲットのtargetsマッピングで宣言することもできます。ターゲットで宣言されたすべてのsyncマッピングは、最上位のすべてのsyncマッピング宣言とマージされます。たとえば、前の例を続けると、次のtargetsレベルのincludeマッピングは、最上位のsyncマッピングのincludeマッピングとマージされます。

targets:
  dev:
    sync:
      include:
        - my_package/dist/delete-me.whl

パス

sync マッピングには、ワークスペースに同期するローカル パスを指定する paths マッピングを含めることができます。pathsマッピングを使用すると、バンドル間で共通のファイルを共有でき、バンドルルートの外部にあるファイルを同期するために使用できます。(バンドル ルートは、databricks.yml ファイルの場所です。 これは、複数のバンドルをホストする 1 つのリポジトリがあり、ライブラリ、コード ファイル、または構成を共有する場合に特に便利です。

指定するパスは、 paths マッピングが設定されているフォルダーに固定されたファイルとディレクトリを基準にした相対パスである必要があります。 1 つ以上のパス値がディレクトリをたどってバンドル ルートの祖先まで移動する場合、ルート パスは動的に決定され、フォルダ構造が損なわれないようにします。 たとえば、バンドル ルート フォルダの名前が my_bundle の場合、この設定は databricks.yml で、バンドル ルートの 1 つ上のレベルにある common フォルダとバンドル ルート自体を同期します。

sync:
  paths:
    - ../common
    - .

このバンドルをデプロイすると、ワークスペース内のフォルダー構造は次のようになります。

common/
  common_file.txt
my_bundle/
  databricks.yml
  src/
    ...

ターゲット

targetsマッピングは、Databricksワークフローを実行する1つ以上のコンテキストを指定します。各ターゲットは、アーティファクト、Databricksワークスペース設定、およびDatabricksジョブまたはパイプラインの詳細の一意のコレクションです。

targetsマッピングは1つ以上のターゲットマッピングで構成され、各ターゲットマッピングは一意のプログラム名（または論理名）を持っている必要があります。

このtargetsマッピングはオプションですが、強くお勧めします。指定された場合、最上位のマッピングとしてのみ表示されます。

最上位 のワークスペース、 成果物、および リソース ・マッピングの設定は、 targets ・マッピングで指定されていない場合に使用されますが、競合する設定はターゲット内の設定によってオーバーライドされます。

ターゲットは、最上位レベルの変数の値をオーバーライドすることもできます。

デフォルト

バンドル・コマンドのターゲット・デフォルトを指定するには、 default マッピングを trueに設定します。 たとえば、 dev という名前のこのターゲットがデフォルトのターゲットです。

targets:
  dev:
    default: true

デフォルト・ターゲットが構成されていない場合、または特定のターゲット内でジョブまたはパイプラインを検証、デプロイおよび実行する場合は、バンドル・コマンドの -t オプションを使用します。

次のコマンドは、dev ターゲットと prod ターゲット内でmy_jobを検証、デプロイ、および実行します。

databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev my_job

databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod my_job

次の例では、2 つのターゲットを宣言します。 最初のターゲットの名前は dev で、バンドル・コマンドにターゲットが指定されていない場合に使用されるデフォルトのターゲットです。 2 番目のターゲットの名前は prod で、このターゲットがバンドル・コマンドに指定されている場合にのみ使用されます。

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>

モードとプリセット

開発を容易にし、 CI/CD ベスト プラクティスを容易にするために、 Databricks Asset Bundles には、pre-本番運用ワークフローと本番運用ワークフローのデフォルト動作を設定するターゲットのデプロイ モードが用意されています。 一部の動作は構成可能でもあります。 詳細については、「 Databricks Asset Bundle のデプロイ モード」を参照してください。

ヒント

バンドルの実行 ID を設定するには、「Databricks Asset Bundles ワークフローの実行 ID を指定する」で説明されているように、ターゲットごとに run_as を指定できます。

ターゲットを開発ターゲットとして扱うように指定するには、 mode マッピング セットを developmentに追加します。 ターゲットを本番運用ターゲットとして扱うように指定するには、 mode マッピングセットを productionに追加します。 たとえば、この prod という名前のターゲットは、本番運用ターゲットとして扱われます。

targets:
  prod:
    mode: production

一部の動作は、 presets マッピングを使用してカスタマイズできます。 使用可能なプリセットのリストについては、「 カスタムプリセット」を参照してください。 次の例は、すべての本番運用リソースにプレフィックスとタグを付けるカスタマイズされた本番運用ターゲットを示しています。

targets:
  prod:
    mode: production
    presets:
      name_prefix: "production_"  # prefix all resource names with production_
      tags:
        prod: true

modeとpresetsの両方が設定されている場合、プリセットはデフォルトのモード動作を上書きします。個々のリソースの設定は、プリセットを上書きします。 たとえば、スケジュールが UNPAUSEDに設定されていても、 trigger_pause_status プリセットが PAUSEDに設定されている場合、スケジュールの一時停止は解除されます。