メインコンテンツまでスキップ

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

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

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

概要​

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

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

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

ヒント

Databricks Asset Bundles の Python サポートにより、Python でリソースを定義できます。「Python での設定」を参照してください。

仕様​

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

YAML
# 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 :re[LDP] (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 認証の種類を決定するように指示されます。一致する host フィールドを持つ複数のプロファイルが .databrickscfg ファイル内に存在する場合は、 profile を使用して、使用する特定のプロファイルを Databricks CLI に指示する必要があります。例については、このセクションで後述する prod ターゲット宣言を参照してください。

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

YAML
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

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

YAML
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 を持つ異なるリモート クラスターを使用します。 notebook_taskマッピングがprodマッピング内で明示的にオーバーライドされていない場合、マッピングはトップレベルのresourcesマッピング内でnotebook_taskマッピングを使用するためにフォールバックするため、prodマッピング内でnotebook_taskマッピングを宣言する必要はありません。

YAML
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ターゲット内でこのジョブを検証、デプロイ、実行するには、次のようにします。

Bash
# 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ターゲット内でこのジョブを検証、デプロイ、実行するには、次のようにします。

Bash
# 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:

YAML
bundle:
  name: hello-bundle

include:
  - 'bundle*.yml'

bundle.resources.yml:

YAML
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:

YAML
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を持つバンドルを宣言しています。

YAML
bundle:
  name: hello-bundle

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

クラスター​

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

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

コンピュート​

注記

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

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の設定を上書きできます。

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

CLI​

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

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

YAML
bundle:
  name: hello-bundle
  databricks_cli_version: '0.218.0' # require Databricks CLI 0.218.0
YAML
bundle:
  name: hello-bundle
  databricks_cli_version: '0.218.*' # allow all patch versions of Databricks CLI 0.218
YAML
bundle:
  name: my-bundle
  databricks_cli_version: '>= 0.218.0' # allow any version of Databricks CLI 0.218.0 or higher
YAML
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 値を取得するためのルックアップを設定します。

YAML
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つだけ含めることができます。

important

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

root_path​

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

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

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

アーティファクト​

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

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

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

注記

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

file_path​

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

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

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

ステートパス​

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

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

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

important

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

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

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

注記

バンドル構成ファイルで 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で定義されているすべてのジョブ、パイプライン、エクスペリメント、モデルに適用されます。

YAML
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ビルドに必要です。デプロイする前に Python wheel ファイルをビルドするには、これを whlに設定します。 他のアーティファクトをビルドする場合、この設定を指定する必要はありません。
  • path はオプションのパスです。パスは、バンドル設定ファイルの場所を基準にした相対パスです。Python wheelビルドの場合は、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を実行します。複数のビルドコマンドを指定するには、各コマンドをダブルアンパサンド（&&）の文字で区切ります。
  • dynamic_version バンドルがホイール ファイルのタイムスタンプに基づいてホイールのバージョンを更新できるようにします。その後、新しいコードを setup.py または pyproject.tomlでバージョンを更新しなくてもデプロイできます。この設定は、 type が whlに設定されている場合にのみ有効です。

次の設定例では、Poetry を使用してホイールを構築します。を使用してホイールをビルドする完全なサンプル バンドルについては、「artifactsPython wheelDatabricksアセット バンドルを使用して ファイルをビルド する」を参照してください。

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

JAR をビルドして Unity Catalog にアップロードする構成例については、「 JAR ファイルを Unity Catalog にアップロードするバンドル」を参照してください。

ヒント

バンドル内のアーティファクトの設定を定義、結合、上書きすることができます (「Databricks アセットバンドルでのアーティファクト設定の定義」を参照してください)。

含める​

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

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

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

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

YAML
include:
  - 'bundle.artifacts.yml'
  - 'bundle.resources.yml'
  - 'bundle.targets.yml'

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

YAML
include:
  - 'bundle*.yml'

リソース​

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

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

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

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

YAML
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 のリストに基づいて、 include マッピングには、バンドルのルートを基準にして明示的に含めるファイル glob、パス glob、またはその両方のリストを含めることができます。
  • バンドルのルートにある .gitignore ファイル内のファイルおよびパス glob のリストと、 include マッピング内のファイル glob とパス glob のリストに基づいて、 exclude マッピングには、バンドルのルートを基準にして明示的に除外するファイル glob、パス glob、またはその両方のリストを含めることができます。

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

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

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

.databricks
my_package/dist

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

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

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

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

YAML
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マッピングとマージされます。

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

道​

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

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

YAML
sync:
  paths:
    - ../common
    - .

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

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

ターゲット​

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

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

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

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

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

デフォルト​

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

YAML
targets:
  dev:
    default: true

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

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

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

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

YAML
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 という名前のターゲットは、本番運用ターゲットとして扱われます。

YAML
targets:
  prod:
    mode: production

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

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

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

に最終更新