Databricks アセット バンドルの構成
この記事では、Databricks アセット バンドルを定義する Databricks アセット バンドル構成ファイルの構文について説明します。 「Databricks アセット バンドルとは」を参照してください
バンドル構成ファイルは YAML 形式で表現する必要があり、少なくとも最上位レベルのバンドルのマッピングを含める必要があります。 各バンドルには、databricks.yml
という名前のバンドル構成ファイルが少なくとも 1 つ (唯一のファイルでもある) 含まれている必要があります。 複数のバンドル構成ファイルがある場合、databricks.yml
ファイルで参照する必要があります。
YAML の詳細については、公式の YAML の仕様とチュートリアルを参照してください。
バンドル構成ファイルを作成して操作するには、「Databricks アセット バンドルの開発ワークフロー」を参照してください。
概要
このセクションでは、バンドル構成ファイルのスキーマを視覚的に表現します。 詳細については、「マッピング」を参照してください。
# These is the default bundle configuration if not otherwise overridden in
# the "targets" top-level mapping.
bundle: # Required.
name: string # Required.
databricks_cli_version: string
compute_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
# 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:
experiments:
<some-unique-programmatic-identifier-for-this-experiment>:
# See the Experiments API's create experiment request payload reference.
jobs:
<some-unique-programmatic-identifier-for-this-job>:
# See the Jobs API's create job request payload reference.
models:
<some-unique-programmatic-identifier-for-this-model>:
# See the Models API's create model request payload reference.
pipelines:
<some-unique-programmatic-identifier-for-this-pipeline>:
# See the Delta Live Tables API's create pipeline 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>"
# 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.
compute_id: string
default: true | false
mode: development
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.
例
バンドル構成ファイルの例を次に示します。 このバンドルは、databricks.yml
という名前のこのローカル バンドル構成ファイルと同じディレクトリにある hello.py
という名前のローカル ファイルのリモート デプロイを指定しています。 指定されたクラスター ID を持つリモート クラスターを使用して、このノートブックがジョブとして実行されます。 リモート ワークスペース URL とワークスペース認証資格情報は、DEFAULT
という名前の呼び出し元のローカル構成プロファイルから読み取られます。
Note
バンドル構成ファイルの移植性を高めるために、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
マッピングが明示的にオーバーライドされていない場合は、最上位レベルの resources
マッピング内で notebook_task
マッピングを使用するようにフォールバックされるため、prod
マッピング内で 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
その他の例については、 バンドルの例の GitHub リポジトリを参照してください。
マッピング
次のセクションでは、最上位レベルのマッピングに基づいて、バンドル構成ファイルの構文について説明します。
バンドル
バンドル構成ファイルには、バンドルのコンテンツと Azure Databricks ワークスペース設定を関連付ける最上位レベルの bundle
マッピングを 1 つだけ含める必要があります。
この bundle
マッピングには、バンドルにプログラム (または論理) 名を指定する name
マッピングが含まれている必要があります。 次の例では、プログラム (または論理) 名 hello-bundle
を使用してバンドルを宣言します。
bundle:
name: hello-bundle
bundle
マッピングは、最上位レベルのターゲット マッピング内の 1 つまたは複数のターゲットの子にすることもできます。 これらの各子 bundle
マッピングでは、ターゲット レベルで既定以外のオーバーライドが指定されます。 しかし、最上位レベルの bundle
マッピングの name
値をターゲット レベルでオーバーライドすることはできません。
compute_id
bundle
マッピングには子 compute_id
マッピングを含めることができます。 このマッピングを使用すると、バンドル構成ファイル内の他の場所で定義されたすべてのクラスターに対するオーバーライドとして使用するクラスターの ID を指定できます。 このオーバーライドは、運用前の開発専用シナリオを対象としています。 compute_id
マッピングは、mode
マッピングが development
に設定されているターゲットに対してのみ機能します。 compute_id
マッピングの詳細については、targets マッピングに関するページを参照してください。
git
バンドルに関連付けられている Git バージョン コントロールの詳細を取得およびオーバーライドできます。 これは、デプロイされたリソースに注釈を付ける場合に便利です。 たとえば、デプロイする機械学習モデルの説明にリポジトリの元の URL を含めることができます。
validate
、deploy
、run
などの bundle
コマンドを実行するたびに、bundle
コマンドでコマンドの構成ツリーに次の既定の設定が取り込まれます。
bundle.git.origin_url
。リポジトリの元の URL を表します。 これは、クローンされたリポジトリからコマンドgit config --get remote.origin.url
を実行した場合に得られるものと同じ値です。 substitutions を使用して、バンドル構成ファイルでこの値を${bundle.git.origin_url}
として参照できます。bundle.git.branch
。リポジトリ内の現在のブランチを表します。 これは、クローンされたリポジトリからコマンドgit branch --show-current
を実行した場合に得られるものと同じ値です。 substitutions を使用して、バンドル構成ファイルでこの値を${bundle.git.branch}
として参照できます。bundle.git.commit
。リポジトリ内のHEAD
コミットを表します。 これは、クローンされたリポジトリからコマンドgit rev-parse HEAD
を実行した場合に得られるものと同じ値です。 substitutions を使用して、バンドル構成ファイルでこの値を${bundle.git.commit}
として参照できます。
Git 設定を取得またはオーバーライドするには、git clone
コマンドを実行して初期化されるローカル ディレクトリなど、Git リポジトリに関連付けられているディレクトリ内にバンドルが存在する必要があります。 ディレクトリが 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
変数
バンドル設定ファイルには、使用する変数設定を指定するための最上位レベルの variables
マッピングを 1 つ含めることができます。 「カスタム変数」を参照してください。
ワークスペース
バンドル構成ファイルには、使用する既定以外の Azure Databricks ワークスペース設定を指定するための最上位レベルの workspace
マッピングを 1 つだけ含めることができます。
この workspace
マッピングには、デプロイとワークフローの実行の両方にワークスペース内で使用する既定以外のルート パスを指定するための root_path
マッピングを含めることができます。以下に例を示します。
workspace:
root_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}
既定では、root_path
の場合、Databricks CLI では、置換を使用する、/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}
の既定のパスが使われます。
この workspace
マッピングには、デプロイとワークフローの実行の両方にワークスペース内で使用する既定以外の成果物パスを指定するための artifact_path
マッピングを含めることもできます。以下に例を示します。
workspace:
artifact_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/artifacts
既定では、artifact_path
の場合、Databricks CLI では、置換を使用する、${workspace.root}/artifacts
の既定のパスが使われます。
..注:: artifact_path
マッピングは Databricks File System (DBFS) パスをサポートしていません。
この workspace
マッピングには、デプロイとワークフローの実行の両方にワークスペース内で使用する既定以外のファイル パスを指定するための file_path
マッピングを含めることができます。以下に例を示します。
workspace:
file_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/files
既定では、file_path
の場合、Databricks CLI では、置換を使用する、${workspace.root}/files
の既定のパスが使われます。
state_path
マッピングの既定値は ${workspace.root}/state
の既定のパスであり、デプロイに関する Terraform 状態情報を格納するためのワークスペース内のパスを表します。
workspace
マッピングには、次の省略可能なマッピングを含め、使用する Azure Databricks 認証メカニズムを指定することもできます。 この workspace
マッピング内で指定されていない場合は、最上位レベルのターゲット マッピング内の 1 つまたは複数のターゲットの子として、workspace
マッピングで指定する必要があります。
重要
Azure Databricks 認証のために、次の workspace
マッピングの値をハードコーディングする必要があります。 たとえば、${var.*}
構文を使用して、これらのマッピングの値にカスタム変数を指定することはできません。
profile
マッピング (または、Databricks CLI を使用してバンドルの検証、デプロイ、実行、破棄のコマンドを実行するときの--profile
または-p
オプション) では、Azure Databricks 認証用にこのワークスペースで使用する構成プロファイルの名前を指定します。 この構成プロファイルは、Databricks CLI を設定したときに作成したものにマップされます。Note
Databricks では、
profile
マッピングではなく、host
マッピング (Databricks CLI を使用してバンドルの検証、デプロイ、実行、破棄のコマンドを実行するときの--profile
または-p
オプション) を使用することをお勧めします。これにより、バンドル構成ファイルの移植性が高まります。host
マッピングを設定することで、Databricks CLI に、.databrickscfg
ファイルで一致するプロファイルを検索し、そのプロファイルのフィールドを使って、使用する Databricks 認証の種類を決定するよう指示します。host
フィールドが一致するプロファイルが.databrickscfg
ファイル内に複数存在する場合は、profile
マッピング (または--profile
または-p
コマンド ライン オプション) を使用して、使用するプロファイルについて Databricks CLI に指示する必要があります。 例については、例に関する記述のprod
ターゲット宣言を参照してください。host
マッピングでは、Azure Databricks ワークスペースの URL を指定します。 「ワークスペース単位のURL」を参照してください。OAuth マシン間 (M2M) 認証の場合、マッピング
client_id
が使用されます。 代わりに、ローカル環境変数DATABRICKS_CLIENT_ID
でこの値を設定することもできます。 または、client_id
値を使用して構成プロファイルを作成してから、profile
マッピングを使用して (または、Databricks CLI を使用してバンドルの検証、デプロイ、実行、破棄のコマンドを実行するときの--profile
または-p
オプションを使用して) プロファイルの名前を指定できます。 「OAuth マシン間 (M2M) 認証」を参照してください。Note
バンドル構成ファイルで Azure Databricks OAuth シークレット値を指定することはできません。 代わりに、ローカル環境変数
DATABRICKS_CLIENT_SECRET
を設定します。 または、client_secret
値を構成プロファイルに追加してから、profile
マッピングを使用して (または、Databricks CLI を使用してバンドルの検証、デプロイ、実行、破棄のコマンドを実行するときの--profile
または-p
オプションを使用して) プロファイルの名前を指定できます。Azure CLI 認証では、マッピング
azure_workspace_resource_id
が使用されます。 代わりに、ローカル環境変数DATABRICKS_AZURE_RESOURCE_ID
でこの値を設定することもできます。 または、azure_workspace_resource_id
値を使用して構成プロファイルを作成してから、profile
マッピングを使用して (または、Databricks CLI を使用してバンドルの検証、デプロイ、実行、破棄のコマンドを実行するときの--profile
または-p
オプションを使用して) プロファイルの名前を指定できます。 「Azure CLI 認証」を参照してください。サービス プリンシパルを使用した Azure クライアント シークレット認証では、マッピング
azure_workspace_resource_id
、azure_tenant_id
、およびazure_client_id
が使用されます。 代わりに、これらの値をそれぞれローカル環境変数DATABRICKS_AZURE_RESOURCE_ID
、ARM_TENANT_ID
、およびARM_CLIENT_ID
で設定することもできます。 または、azure_workspace_resource_id
、azure_tenant_id
、azure_client_id
値を使用して構成プロファイルを作成してから、profile
マッピングを使用して (または、Databricks CLI を使用してバンドルの検証、デプロイ、実行、破棄のコマンドを実行するときの--profile
または-p
オプションを使用して) プロファイルの名前を指定できます。 「Microsoft Entra ID サービス プリンシパル認証」を参照してください。Note
バンドル構成ファイルで Azure クライアント シークレット値を指定することはできません。 代わりに、ローカル環境変数
ARM_CLIENT_SECRET
を設定します。 または、azure_client_secret
値を構成プロファイルに追加してから、profile
マッピングを使用して (または、Databricks CLI を使用してバンドルの検証、デプロイ、実行、破棄のコマンドを実行するときの--profile
または-p
オプションを使用して) プロファイルの名前を指定できます。Azure マネージド ID 認証では、マッピング
azure_use_msi
、azure_client_id
、azure_workspace_resource_id
が使用されます。 代わりに、これらの値をそれぞれローカル環境変数ARM_USE_MSI
、ARM_CLIENT_ID
、およびDATABRICKS_AZURE_RESOURCE_ID
で設定することもできます。 または、azure_use_msi
、azure_client_id
、azure_workspace_resource_id
値を使用して構成プロファイルを作成してから、profile
マッピングを使用して (または、Databricks CLI を使用してバンドルの検証、デプロイ、実行、破棄のコマンドを実行するときの--profile
または-p
オプションを使用して) プロファイルの名前を指定できます。 「Azure マネージド ID 認証」を参照してください。azure_environment
マッピングでは、特定の API エンドポイントのセットに対して Azure 環境の種類 (Public、UsGov、China、Germany など) を指定します。 既定値はPUBLIC
です。 代わりに、ローカル環境変数ARM_ENVIRONMENT
でこの値を設定することもできます。 または、azure_environment
値を構成プロファイルに追加してから、profile
マッピングを使用して (または、Databricks CLI を使用してバンドルの検証、デプロイ、実行、破棄のコマンドを実行するときの--profile
または-p
オプションを使用して) プロファイルの名前を指定できます。azure_login_app_id
マッピングは非運用であり、内部使用のために予約されています。auth_type
マッピングでは、特に Databricks CLI で予期しない認証の種類が推測された場合に、使用する Azure 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 ホイール ファイルを構築するには、このマッピングをwhl
に設定する必要があります。path
は、バンドル構成ファイルの場所から Python ホイール ファイルのsetup.py
ファイルの場所への、省略可能な相対パスです。path
が含まれていない場合、Databricks CLI は、バンドルのルートで Python ホイール ファイルのsetup.py
ファイルの検索を試行します。files
は省略可能なマッピングであり、複雑なビルド手順に含める既定以外の場所を指定するために使用できるsource
子マッピングが含まれています。 場所は、バンドル構成ファイルの場所からの相対パスとして指定されます。build
は、デプロイの前にローカルで実行する既定以外のビルド コマンドの省略可能なセットです。 Python ホイール ビルドの場合、Databricks CLI は、ビルドを実行する Pythonwheel
パッケージのローカル インストールを検出できると想定して、各バンドルのデプロイ中に既定でコマンドpython setup.py bdist_wheel
を実行します。 複数のビルド コマンドを指定するには、各コマンドを二重アンパサンド (&&
) 文字で区切ります。
artifacts
を使用するサンプル バンドルなどの詳細については、「Databricks アセット バンドルを使用した Python ホイール ファイルの開発」を参照してください。
ヒント
「Databricks アセット バンドルで成果物の設定を動的に定義する」で説明されている手法を使用して、バンドル内の成果物の設定を定義、結合、オーバーライドできます。
インクルード
include
配列では、バンドル内に含める構成ファイルを含むパス glob のリストを指定します。 これらのパス glob は、パス glob が指定されているバンドル構成ファイルの場所に対する相対パスです。
既定で、Databricks CLI のバンドル内には構成ファイルが含まれていません。 include
配列を使用して、databricks.yml
ファイル自体以外の、バンドル内に含めるすべての構成ファイルを指定する必要があります。
この include
配列は、最上位レベルのマッピングとしてのみ表示できます。
バンドル構成ファイルの次の例には、3 個の指定された構成ファイルが含まれています。 これらのファイルは、バンドル構成ファイルと同じディレクトリにあります。
include:
- "bundle.artifacts.yml"
- "bundle.resources.yml"
- "bundle.targets.yml"
バンドル構成ファイルの次の例には、bundle
で始まり、.yml
で終わるファイル名を持つすべてのファイルが含まれています。 これらのファイルは、バンドル構成ファイルと同じディレクトリにあります。
include:
- "bundle*.yml"
リソース
resources
マッピングには、バンドルに使われる Azure Databricks リソースに関する情報を指定します。
この resources
マッピングは、最上位レベルのマッピングとして表示される場合や、最上位レベルのターゲット マッピングに含まれる 1 つ以上のターゲットの子である場合があり、サポートされるリソースの種類の 0 個または 1 個が含まれます。 各リソースの種類マッピングには 1 つ以上の個別のリソース宣言が含まれており、それぞれに一意の名前が必要です。 これらの個々のリソース宣言では、YAML で表される対応するオブジェクトの作成操作の要求ペイロードを使用して、リソースを定義します。 リソースでサポートされるプロパティは、対応するオブジェクトのサポートされるフィールドです。
作成操作の要求ペイロードについては「Databricks REST API リファレンス」に説明があり、databricks bundle schema
コマンドがサポートされるすべてのオブジェクト スキーマを出力します。 さらに、バンドル構成ファイルで不明なリソース プロパティが見つかった場合、databricks bundle validate
コマンドが警告を返します。
次の表は、バンドルでサポートされているリソースの種類と、対応するペイロードに関するドキュメントのリンクをまとめたものです。
リソースの種類 | リソース マッピング |
---|---|
jobs |
ジョブ マッピング: POST /api/2.1/jobs/create 詳細については、ジョブ タスクの種類と新しいジョブ クラスター設定のオーバーライドに関する記事を参照してください。 |
pipelines |
パイプライン マッピング: POST /api/2.0/pipelines |
experiments |
実験マッピング: POST /api/2.0/mlflow/experiments/create |
models |
モデル マッピング: POST /api/2.0/mlflow/registered-models/create |
model_serving_endpoints |
モデル提供エンドポイント マッピング: POST /api/2.0/serving-endpoints |
registered_models (Unity Catalog) |
Unity Catalog モデル マッピング: POST /api/2.1/unity-catalog/models |
リソース宣言によって参照されるフォルダーとファイルへのすべてのパスは、これらのパスが指定されているバンドル構成ファイルの場所からの相対パスです。
次の例では、リソース キーが hello-job
のジョブとリソース キーが hello-pipeline
のパイプラインを宣言します。
resources:
jobs:
hello-job:
name: hello-job
tasks:
- task_key: hello-task
existing_cluster_id: 1234-567890-abcde123
notebook_task:
notebook_path: ./hello.py
pipelines:
hello-pipeline:
name: hello-pipeline
clusters:
- label: default
num_workers: 1
development: true
continuous: false
channel: CURRENT
edition: CORE
photon: false
libraries:
- notebook:
path: ./pipeline.py
同期
次の規則に応じて、sync
配列では、バンドル デプロイ内に含めるか、バンドル デプロイから除外するファイルまたはパス glob のリストを指定します。
- バンドルのルート内の
.gitignore
ファイル内のファイルとパス glob のリストに基づいて、include
マッピングには、明示的に含めるために、バンドルのルートに対して相対的なファイル glob、パス glob、またはその両方のリストを含めることができます。 - バンドルのルート内の
.gitignore
ファイル内のファイルとパス glob のリストに加え、include
マッピング内のファイルとパス glob のリストに基づいて、exclude
マッピングには、明示的に除外するために、バンドルのルートに対して相対的なファイル glob、パス glob、またはその両方のリストを含めることができます。
指定されたフォルダーとファイルへのすべてのパスは、これらのパスが指定されているバンドル構成ファイルの場所に対する相対パスです。
include
および exclude
ファイルとパスのパターンの構文は、標準の .gitignore
パターン構文に従います。 「gitignore パターン形式」を参照してください。
たとえば、次の .gitignore
ファイルに次のエントリが含まれている場合:
.databricks
my_package/dist
また、バンドル構成ファイルには、次の include
マッピングが含まれています。
sync:
include:
- my_package/dist/*.whl
その後、ファイル拡張子が *.whl
の my_package/dist
フォルダー内のすべてのファイルが含まれます。 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
databricks bundle validate --output json
を実行すると、結果のグラフの関連部分は次のようになります。
"sync": {
"include": [
"my_package/dist/*.whl",
"my_package/dist/delete-me.whl"
],
"exclude": [
"my_package/dist/delete-me.whl"
]
}
ターゲット
targets
マッピングでは、Azure Databricks ワークフローを実行する 1 つまたは複数のコンテキストを指定します。 各 ''ターゲット'' は、成果物、Azure Databricks ワークスペース設定、Azure Databricks ジョブまたはパイプラインの詳細の一意のコレクションです。
この targets
マッピングは省略可能ですが、強くお勧めします。 指定されている場合、最上位レベルのマッピングとしてのみ表示できます。 targets
マッピングが指定されていない場合は、最上位のワークスペース、成果物、およびリソース マッピングの設定が常に使用されます。
targets
マッピングは 1 つまたは複数のターゲット マッピングで構成され、それぞれに一意のプログラム (または論理) 名が必要です。
ターゲット マッピングで workspace
、artifacts
、または resources
子マッピングが指定されていない場合、そのターゲットでは最上位レベルの workspace
、resources
、および artifacts
マッピングの設定が使用されます。
ターゲット マッピングで workspace
、artifacts
、または resources
マッピングが指定され、最上位レベルの workspace
、artifacts
、または resources
マッピングも存在する場合、競合する設定はターゲット内の設定によってオーバーライドされます。
ターゲットでは、最上位の変数の値をオーバーライドすることもできます。
特に指定しない限り、ターゲットが既定のものであることを指定するには、default
マッピングを追加し、true
に設定します。 たとえば、dev
という名前のこのターゲットは既定のターゲットです。
targets:
dev:
default: true
ターゲットが開発ターゲットとして扱われるように指定するには、development
に設定された mode
マッピングを追加します。 ターゲットが運用ターゲットとして扱われるように指定するには、production
に設定された mode
マッピングを追加します。 たとえば、prod
という名前のこのターゲットは、運用ターゲットとして扱われます。
targets:
prod:
mode: production
mode
を指定すると、運用前ワークフローと運用ワークフローの該当する既定動作のコレクションが提供されます。 詳細については、「Databricks アセット バンドルのデプロイ モード」を参照してください。 さらに、「Databricks アセット バンドル ワークフローの実行 ID を指定する」の説明に従って、ターゲットごとに run_as
を指定することができます。
次の例では、2 つのターゲットを宣言します。 最初のターゲットには dev
というプログラム (または論理) 名があり、既定のターゲットです。 2 つ目のターゲットには prod
というプログラム (または論理) 名があり、既定のターゲットではありません。 この 2 つ目のターゲットでは、認証用に PROD
という名前の Azure Databricks 接続プロファイルを使用します。
targets:
dev:
default: true
prod:
workspace:
host: https://<production-workspace-url>
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 <job-or-pipeline-programmatic-name>
# 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 <job-or-pipeline-programmatic-name>
代わりに 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 <job-or-pipeline-programmatic-name>
カスタム変数
カスタム変数を使用して、バンドル構成ファイルをよりモジュール化し、再利用可能にすることができます。 たとえば、既存のクラスターの ID を表す変数を宣言した後、バンドル構成ファイルの元のコードを変更せずに、その変数の値を別のクラスター ID に変更したい場合があります (複数のターゲット内のさまざまなワークフロー実行のため)。
バンドル構成ファイル内の variables
マッピングの中で、1 つ以上の変数を宣言することができます。 次の形式に従って、変数ごとにオプションの説明、既定値、または ID 値を取得するルックアップを設定することができます。
variables:
<variable-name>:
description: <optional-description>
default: <optional-default-value>
lookup:
<optional-object-type>: <optional-object-name>
たとえば、既定値が 1234-567890-abcde123
の my_cluster_id
という名前の変数を宣言し、既定値が ./hello.py
の my_notebook_path
という名前の変数を宣言するには、次のようにします。
variables:
my_cluster_id:
description: The ID of an existing cluster.
default: 1234-567890-abcde123
my_notebook_path:
description: The path to an existing notebook.
default: ./hello.py
その宣言の一部として変数に default
値を指定しない場合は、後でコマンド ライン、環境変数、またはバンドル構成ファイル内の他の場所で値を指定する必要があります。 これらの方法については、このセクションで後述します。
Note
変数値を指定するためにどの方法を選んでも、デプロイと実行の両方のステージで同じ方法を使用してください。 そうしないと、デプロイの時点から、その既存のデプロイに基づくジョブまたはパイプラインの実行までの間に予期しない結果が得られる可能性があります。
バンドル構成ファイル内でカスタム変数を参照するには、置換を使用します。 変数の場合は、${var.<variable_name>}
形式を使用します。 たとえば、my_cluster_id
と my_notebook_path
という名前の変数を参照するには、次のようにします。
resources:
jobs:
hello-job:
name: hello-job
tasks:
- task_key: hello-task
existing_cluster_id: ${var.my_cluster_id}
notebook_task:
notebook_path: ${var.my_notebook_path}
変数の値を設定する
変数に default
値を指定していない場合、または変数の default
値を一時的にオーバーライドする場合は、次の方法のいずれかを使用して変数の新しい一時的な値を指定します。
validate
、deploy
、run
などのbundle
コマンドの一部として変数の値を指定します。 これを行うには、オプション--var="<key>=<value>"
を使用します。ここで、<key>
は変数の名前、<value>
は変数の値です。 たとえば、bundle validate
コマンドの一部として、my_cluster_id
という名前の変数に1234-567890-abcde123
の値を指定し、my_notebook_path
という名前の変数に./hello.py
の値を指定するには、以下を実行します。databricks bundle validate --var="my_cluster_id=1234-567890-abcde123,my_notebook_path=./hello.py" # Or: databricks bundle validate --var="my_cluster_id=1234-567890-abcde123" --var="my_notebook_path=./hello.py"
環境変数を設定して、変数の値を指定します。 環境変数の名前は
BUNDLE_VAR_
で始まる必要があります。 環境変数を設定するには、オペレーティング システムのドキュメントを参照してください。 たとえば、my_cluster_id
という名前の変数に1234-567890-abcde123
の値を指定し、my_notebook_path
という名前の変数に./hello.py
の値を指定するには、validate
、deploy
、run
などのbundle
コマンドを呼び出す前に、次のコマンドを実行します。Linux および macOS の場合:
export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
Windows の場合:
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"
または、たとえば、Linux や macOS の場合、
validate
、deploy
、run
などのbundle
コマンドの一部として、変数の値を指定します。BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
または Windows の場合:
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
バンドル構成ファイル内で変数の値を指定します。 これを行うには、この形式に従って、
targets
マッピング内でvariables
マッピングを使用します。variables: <variable-name>: <value>
たとえば、2 つの個別のターゲットについて、
my_cluster_id
とmy_notebook_path
という名前の変数に値を指定するには、次のようにします。targets: dev: variables: my_cluster_id: 1234-567890-abcde123 my_notebook_path: ./hello.py prod: variables: my_cluster_id: 2345-678901-bcdef234 my_notebook_path: ./hello.py
前の例では、Databricks CLI によって、次の順序で変数 my_cluster_id
と my_notebook_path
の値が検索されます。一致する各変数の値が見つかると停止され、その変数の他の場所はスキップされます。
bundle
コマンドの一部として指定された--var
オプション内。BUNDLE_VAR_
で始まる環境変数セット内。- バンドル構成ファイル内の
targets
マッピングの中の任意のvariables
マッピング内。 - バンドル構成ファイル内の最上位レベルの
variables
マッピングの中で、その変数を定義する任意のdefault
値。
オブジェクトの ID 値を取得する
alert
、cluster_policy
、cluster
、dashboard
、instance_pool
、job
、metastore
、pipeline
、query
、service_principal
、warehouse
オブジェクト型の場合は、次の形式を使用して、名前付きオブジェクトの ID を取得するカスタム変数の lookup
を定義することができます。
variables:
<variable-name>:
lookup:
<object-type>: "<object-name>"
変数に対して lookup が定義されている場合、指定した名前を持つオブジェクトの ID が変数の値として使用されます。 これにより、オブジェクトの正しい解決済み ID が、常に変数で使用されることが保証されます。
Note
指定した名前を持つオブジェクトが存在しない場合、または指定した名前を持つオブジェクトが複数存在する場合は、エラーが発生します。
たとえば次の構成において、${var.my_cluster_id}
は 12.2 shared クラスターの ID に置き換えられます。
variables:
my_cluster_id:
description: An existing cluster
lookup:
cluster: "12.2 shared"
resources:
jobs:
my_job:
name: "My Job"
tasks:
- task_key: TestTask
existing_cluster_id: ${var.my_cluster_id}
置換
substitutions を使用して、バンドル構成ファイルをよりモジュール化し、再利用可能にすることができます。
ヒント
また、ジョブ実行に関するコンテキストをジョブ タスクに渡すために、ジョブ パラメーター値に動的値参照を使用することもできます。 「ジョブ実行に関するコンテキストをジョブ タスクに渡す」を参照してください。
たとえば、bundle validate --output json
コマンドを実行すると、このようなグラフが表示されることがあります (簡潔にするために、省略記号は省略されたコンテンツを示します)。
{
"bundle": {
"name": "hello-bundle",
"target": "dev",
"...": "..."
},
"workspace": {
"...": "...",
"current_user": {
"...": "...",
"userName": "someone@example.com",
"...": "...",
},
"...": "..."
},
"...": {
"...": "..."
}
}
前の例では、substitution ${workspace.current_user.userName}
を使用してバンドル構成ファイル内の値 someone@example.com
を参照できました。
同様に、次の置換が使用されます。
/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}
次のようなバンドル構成ファイル内 (簡潔にするために、内容が省略されていることを省略記号で示しています):
bundle:
name: hello-bundle
workspace:
root_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}
# ...
targets:
dev:
default: true
bundle validate --output json
コマンドを実行すると、次のグラフに解決されます (簡潔にするために、省略記号は省略されたコンテンツを示します)。
{
"bundle": {
"name": "hello-bundle",
"target": "dev",
"...": "..."
},
"workspace": {
"profile": "DEFAULT",
"current_user": {
"...": "...",
"userName": "someone@example.com",
"...": "...",
},
"root": "/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev",
"...": "..."
},
"...": {
"...": "..."
}
}
名前付きリソースの置換を作成することもできます。 たとえば、my_pipeline
という名前で構成されたパイプラインの場合、${resources.pipelines.my_pipeline.target}
は my_pipeline
のターゲットの値の置換です。
有効な置換を判別するには、「REST API リファレンス」で記載されているスキーマ階層を使用するか、bundle schema
コマンドの出力を使用することができます。
一般的に使用される置換を次に示します。
${bundle.name}
${bundle.target} # Use this substitution instead of ${bundle.environment}
${workspace.host}
${workspace.current_user.short_name}
${workspace.current_user.userName}
${workspace.file_path}
${workspace.root_path}
${resources.jobs.<job-name>.id}
${resources.models.<model-name>.name}
${resources.pipelines.<pipeline-name>.name}
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示