Databricks アセット バンドルの構成
この記事では、Databricksアセットバンドルを定義するDatabricksアセットバンドルの構成ファイルの構文について説明します。「Databricksアセットバンドルとは?」を参照してください。
バンドル構成ファイルはYAML形式で表現する必要があり、少なくとも最上位のバンドルマッピングが含まれている必要があります。各バンドルには、databricks.yml
という名前のバンドル構成ファイルが少なくとも1つ(そして1つだけ)含まれている必要があります。バンドル構成ファイルが複数ある場合は、include
マッピングを使用してdatabricks.yml
ファイルで参照する必要があります。
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:
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.
# 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}
)。bundle.git.commit
これはリポジトリ内のHEAD
コミットを表します。これは、クローンされたリポジトリからコマンドgit rev-parse HEAD
を実行した場合に取得される値と同じです。バンドル構成ファイルでこの値を参照するには、 置換を使用して${bundle.git.commit}
のように指定します。
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_CLIENT_SECRET
に設定します。あるいは、client_secret
値を構成プロファイルに追加し、profile
マッピングでプロファイル名を指定することもできます(または、Databricks CLIでバンドルの検証、デプロイ、実行、破棄コマンドを実行する際に--profile
または-p
オプションを使用します)。
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は、ビルドを実行するためのPythonwheel
パッケージのローカルインストールを見つけることができることを前提としており、各バンドルのデプロイメント中にデフォルトでコマンドpython setup.py bdist_wheel
を実行します。複数のビルドコマンドを指定するには、各コマンドをダブルアンパサンド(&&
)の文字で区切ります。
artifacts
を使用するサンプルバンドルなど、詳細については、「Databricksアセットバンドルを使用してPython wheelファイルを開発する」を参照してください。
ヒント
バンドル内のアーティファクト設定を定義、結合、および上書きするには、「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
コマンドは、未知のリソースプロパティがバンドル構成ファイルで見つかった場合に警告を返します。
次の表は、バンドルでサポートされているリソースタイプと、対応するペイロードのドキュメントへのリンクを示しています。
リソースタイプ |
リソースマッピング |
---|---|
クラスター マッピング: POST /api/2.1/クラスター/create |
|
ダッシュボードのマッピング: POST /api/2.0/preview/sql/dashboards |
|
experiment |
エクスペリメントマッピング:POST /api/2.0/mlflow/experiments/create |
ジョブマッピング:POST /api/2.1/jobs/create 詳細については、「タスクのタイプ」および「新しいジョブクラスター設定への上書き」を参照してください。 |
|
パイプラインマッピング: POST /api/2.0/pipelines |
|
model |
|
model_serving_endpoint |
モデルサービングエンドポイントマッピング: POST /api/2.0/serving-endpoints |
registered_model(Unity Catalog) |
Unity Catalog モデルのマッピング: POST /api/2.1/unity-catalog/models |
schema(Unity Catalog) |
Unity Catalog スキーママッピング: POST /api/2.1/unity-catalog/schemas |
リソース宣言で参照されるフォルダとファイルへのすべてのパスは、これらのパスが指定されているバンドル構成ファイルの場所と相対するものです。
クラスター
クラスター リソースを使用すると、All-Purposeクラスターを作成できます。 次の例では、 my_cluster
という名前のクラスターを作成し、それを my_job
でノートブックを実行するために使用するクラスターとして設定します。
bundle:
name: clusters
resources:
clusters:
my_cluster:
num_workers: 2
node_type_id: "i3.xlarge"
autoscale:
min_workers: 2
max_workers: 7
spark_version: "13.3.x-scala2.12"
spark_conf:
"spark.executor.memory": "2g"
jobs:
my_job:
tasks:
- task_key: test_task
existing_cluster_id: ${resources.clusters.my_cluster.id}
notebook_task:
notebook_path: "./src/my_notebook.py"
ダッシュボード
ダッシュボードリソースを使用すると、AI/BI ダッシュボードをバンドルで管理できます。 AI/BIダッシュボードに関する情報については、「ダッシュボード」を参照してください。
次の例では、サンプルの NYC タクシー乗車分析 ダッシュボードを含め、Databricks ワークスペースにデプロイします。
resources:
dashboards:
nyc_taxi_trip_analysis:
display_name: "NYC Taxi Trip Analysis"
file_path: ../src/nyc_taxi_trip_analysis.lvdash.json
warehouse_id: ${var.warehouse_id}
UI を使用してダッシュボードを変更する場合、UI を使用して明示的に更新しない限り、UI を介して行った変更は、ローカル バンドル内のダッシュボード JSON ファイルに適用されません bundle generate
。 --watch
オプションを使用すると、ダッシュボードに対する変更を継続的にポーリングして取得できます。バンドル設定ファイルの生成を参照してください。
さらに、リモート ワークスペース内のものとは異なるダッシュボード JSON ファイルを含むバンドルをデプロイしようとすると、エラーが発生します。 デプロイを強制し、リモート ワークスペースのダッシュボードをローカル ダッシュボードで上書きするには、 --force
オプションを使用します。 バンドルのデプロイを参照してください。
ジョブ
次の例では、hello-job
のリソースキーを持つジョブを宣言しています。
resources:
jobs:
hello-job:
name: hello-job
tasks:
- task_key: hello-task
existing_cluster_id: 1234-567890-abcde123
notebook_task:
notebook_path: ./hello.py
パイプライン
次の例では、hello-pipeline
のリソースキーを持つパイプラインを宣言しています。
resources:
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
スキーマ
スキーマ リソースの種類を使用すると、バンドルの一部として作成されたワークフローとパイプライン内のテーブルやその他のアセットの Unity Catalog スキーマを定義できます。 スキーマは、他のリソースタイプとは異なり、次の制限があります。
スキーマリソースの所有者は常にデプロイメントユーザーであり、変更することはできません。バンドルに
run_as
が指定されている場合、スキーマに対する操作では無視されます。対応するスキーマオブジェクト作成APIがサポートするフィールドのみ
schema
リソースで利用可能です。例えば、enable_predictive_optimization
は更新APIでしか利用できないため、サポートされていません。
次の例では、リソースキーmy_pipeline
を使用して、キーmy_schema
をターゲットとしてUnity Catalogスキーマを作成するパイプラインを宣言しています。
resources:
pipelines:
my_pipeline:
name: test-pipeline-{{.unique_id}}
libraries:
- notebook:
path: ./nb.sql
development: true
catalog: main
target: ${resources.schemas.my_schema.id}
schemas:
my_schema:
name: test-schema-{{.unique_id}}
catalog_name: main
comment: This schema was created by DABs.
最上位の付与マッピングは Databricks Asset Bundle でサポートされていないため、スキーマの付与を設定する場合は、 schemas
マッピング内でスキーマの付与を定義します。
schemas:
my_schema:
name: test-schema
grants:
- principal: users
privileges:
- CAN_MANAGE
- principal: my_team
privileges:
- CAN_READ
catalog_name: main
comment: "my schema with grants"
同期
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
に設定されている場合、スケジュールの一時停止は解除されます。