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

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

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

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

databricks.yml​

バンドルには、バンドルプロジェクトフォルダのルートに databricks.yml という名前の設定ファイルが1つ(1つだけ)含まれている必要があります。databricks.yml はバンドルを定義するメイン構成ファイルですが、 include マッピング内の他の構成ファイル (リソース構成ファイルなど) を参照できます。バンドル構成は YAML で表されます。YAML の詳細については、公式の YAML 仕様を参照してください。

最も簡単な databricks.yml は、必要な最上位マッピング ・バンドル内にあるバンドル名とターゲット・デプロイメントを定義することです。

YAML
bundle:
  name: my_bundle

targets:
  dev:
    default: true

すべての最上位マッピングの詳細については、「 マッピング」を参照してください。

ヒント

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
  deployment: Map
  git:
    origin_url: string
    branch: string

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

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

# 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 default artifact settings if not otherwise overridden in
# the targets top-level mapping.
artifacts:
  <some-unique-artifact-identifier>:
    build: string
    dynamic_version: boolean
    executable: string
    files:
      - source: string
    path: string
    type: string

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

# These are the default workspace settings if not otherwise overridden in
# the 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. 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
  resource_path: string
  root_path: string
  state_path: string

# These are the permissions to apply to resources 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 resource settings if not otherwise overridden in
# the targets top-level mapping.
resources:
  apps:
    <unique-app-name>:
      # See the REST API create request payload reference for apps.
  clusters:
    <unique-cluster-name>:
      # See the REST API create request payload reference for clusters.
  dashboards:
    <unique-dashboard-name>:
      # See the REST API create request payload reference for dashboards.
  experiments:
    <unique-experiment-name>:
      # See the REST API create request payload reference for experiments.
  jobs:
    <unique-job-name>:
      # See REST API create request payload reference for jobs.
  model_serving_endpoint:
    <unique-model-serving-endpoint-name>:
    # See the model serving endpoint request payload reference.
  models:
    <unique-model-name>:
      # See the REST API create request payload reference for models (legacy).
  pipelines:
    <unique-pipeline-name>:
      # See the REST API create request payload reference for :re[LDP] (pipelines).
  quality_monitors:
    <unique-quality-monitor-name>:
    # See the quality monitor request payload reference.
  registered_models:
    <unique-registered-model-name>:
    # See the registered model request payload reference.
  schemas:
    <unique-schema-name>:
      # See the Unity Catalog schema request payload reference.
  secret_scopes:
    <unique-secret-scope-name>:
      # See the secret scope request payload reference.
  volumes:
    <unique-volume-name>:
    # See the Unity Catalog volume request payload reference.

# 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.
    default: boolean
    git: Map
    mode: string
    permissions:
      # See the preceding "permissions" syntax.
    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という名前) から読み取られます。

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

次の例では、異なるリモートワークスペースURLとワークスペース認証資格証明を使用する prod という名前のターゲットを追加します。これらは、指定されたワークスペースURLと一致する呼び出し元の .databrickscfg ファイルの host エントリから読み取られます。 このジョブは、同じノートブックを実行しますが、指定されたクラスター ID を持つ異なるリモート クラスターを使用します。

注記

Databricks では、バンドル構成ファイルの移植性が向上するため、可能な限り default マッピングではなく host マッピングを使用することをお勧めします。host マッピングを設定すると、Databricks CLI は .databrickscfg ファイル内で一致するプロファイルを検索し、そのプロファイルのフィールドを使用して使用する Databricks 認証の種類を決定するように指示されます。一致する host フィールドを持つプロファイルが複数存在する場合は、bundle コマンドの --profile オプションを使用して、使用するプロファイルを指定する必要があります。

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 ・ターゲット内で検証、デプロイ、および実行します。バンドルのライフサイクルの詳細については、「 Databricks アセット バンドルの開発」を参照してください。

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

モジュール化を進め、バンドル間での定義と設定の再利用を改善するには、バンドル設定を個別のファイルに分割します。

YAML
# databricks.yml

bundle:
  name: hello-bundle

include:
  - '*.yml'
YAML
# hello-job.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
YAML
# 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を持つバンドルを宣言しています。

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 バージョン管理の詳細を取得してオーバーライドできるため、後でリソースを識別するために使用できるデプロイメタデータを伝播するのに役立ちます。たとえば、CI/CD によってデプロイされたジョブのリポジトリの起点をトレースできます。

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

run_as​

run_as 設定では、バンドルの実行に使用するuser_nameまたはservice_principal_nameを指定します。これにより、バンドル ジョブまたはパイプラインのデプロイに使用される ID を、ジョブまたはパイプラインの実行に使用される ID から分離できます。

「Databricks Asset Bundles ワークフローの実行 ID を指定する」を参照してください。

含める​

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'

同期​

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/
    ...

アーティファクト​

最上位の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 アセットバンドルでのアーティファクト設定の定義」を参照してください)。

変数​

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

リソース​

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 リソース」および「バンドルの設定例」を参照してください。

ターゲット​

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に設定されている場合、スケジュールの一時停止は解除されます。

に最終更新