本文介绍用于定义 Databricks 资产捆绑包的 Databricks 资产捆绑包的语法。 请参阅什么是 Databricks 资产捆绑包?。
若要创建和使用捆绑包,请参阅 开发 Databricks 资产捆绑包。
databricks.yml
捆绑包必须包含一个(且只有一个)配置文件,该文件在捆绑项目文件夹的根目录中命名 databricks.yml
。
databricks.yml
是定义捆绑包的主配置文件,但它可以在映射中 include
引用其他配置文件,例如资源配置文件。 捆绑配置以 YAML 表示。 有关 YAML 的详细信息,请参阅官方 YAML 规范。
最简单的 databricks.yml
定义捆绑包名称,该名称位于所需的顶级映射 捆绑包和目标部署中。
bundle:
name: my_bundle
targets:
dev:
default: true
有关所有顶级映射的详细信息,请参阅 “映射”。
提示
借助对 Databricks 资产捆绑包的 Python 支持,可以在 Python 中定义资源。 请参阅 Python 中的捆绑配置。
规范
以下 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
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 scripts that can be run.
scripts:
<some-unique-script-name>:
content: string
# 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 中的捆绑示例存储库。
以下示例捆绑配置指定与捆绑配置文件位于同一目录中的 hello.py
本地文件 databricks.yml
。 它使用具有指定群集 ID 的远程群集将此笔记本作为作业运行。 远程工作区 URL 和工作区身份验证凭据是从调用方名为 DEFAULT
的本地配置文件中读取的。
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
的目标,该目标使用不同的远程工作区 URL 和工作区身份验证凭据,这些凭据是从调用者的 .databrickscfg
文件中与指定工作区 URL 匹配的 host
条目中读取的。 此作业运行相同的笔记本,但使用具有指定群集 ID 的不同远程群集。
注意
Databricks 建议尽可能使用 host
映射而不是 default
映射,因为这样可以提高捆绑包配置文件的可移植性。 设置 host
映射会指示 Databricks CLI 在 .databrickscfg
文件中查找匹配的配置文件,然后使用该配置文件的字段来确定要使用的 Databricks 身份验证类型。 如果存在具有匹配 host
字段的多个配置文件,则必须使用 --profile
捆绑命令上的选项来指定要使用的配置文件。
请注意,不需要在 notebook_task
映射中声明 prod
映射,因为如果未显式替代 notebook_task
映射中的 resources
映射,它会回退为使用顶级 notebook_task
映射中的 prod
映射。
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 资产捆绑包。
# 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:
- '*.yml'
# 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
# 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
映射
以下部分介绍了捆绑包配置顶级映射。 有关配置参考,请参阅 配置参考。
捆绑销售
捆绑包配置文件只能包含一个顶级 bundle
映射,该映射关联捆绑包的内容和 Azure Databricks 工作区设置。
此 bundle
映射必须包含一个用于指定捆绑包的编程(或逻辑)名称的 name
映射。 以下示例使用编程(或逻辑)名称 hello-bundle
声明一个捆绑包。
bundle:
name: hello-bundle
bundle
映射还可以是顶级目标映射中一个或多个目标的子级。 其中的每个子 bundle
映射在目标级别指定任何非默认替代。 但是,不能在目标级别替代顶级 bundle
映射的 name
值。
cluster_id(集群标识)
bundle
映射可以拥有一个子 cluster_id
映射。 通过此映射,可以指定要替代在捆绑包配置文件中其他位置定义的任何和所有群集的群集的 ID。 有关如何检索群集 ID 的信息,请参阅群集 URL 和 ID。
cluster_id
替代适用于仅开发应用场景,并且仅支持其 mode
映射设置为 development
的目标。 有关 target
映射的详细信息,请参阅目标。
compute_id
注意
此设置已弃用。 请改用 cluster_id。
bundle
映射可以拥有一个子 compute_id
映射。 通过此映射,可以指定要替代在捆绑包配置文件中其他位置定义的任何和所有群集的群集的 ID。
git
可以检索和替代与捆绑包关联的 Git 版本控制详细信息,这对于传播稍后可用于标识资源的部署元数据非常有用。 例如,您可以溯源由 CI/CD 部署的作业所在的存储库。
每当运行 bundle
命令(例如 validate
、deploy
或 run
)时,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 设置为空。
如果需要,可以替代顶级 origin_url
映射的 branch
映射中的 git
和 bundle
设置,如下所示:
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
run_as
该 run_as
设置指定 user_name
或 service_principal_name
用于运行捆绑包。 它提供将用于部署捆绑作业或管道的标识与用于运行作业或管道的标识分开的功能。
请参阅 指定 Databricks 资产捆绑包工作流的运行标识。
包括
include
数组指定路径 glob 列表,其中包含要放入捆绑包中的配置文件。 这些路径 glob 是相对于以下位置的值:指定了路径 glob 的捆绑包配置文件所在的位置。
Databricks CLI 捆绑包中不包含任何配置文件。 必须使用 include
数组来指定要包含在捆绑包中的任何及所有配置文件(除了 databricks.yml
文件本身)。
此 include
数组只能显示为顶级映射。
以下示例配置包含三个配置文件。 这些文件与捆绑配置文件位于同一文件夹中:
include:
- 'bundle.artifacts.yml'
- 'bundle.resources.yml'
- 'bundle.targets.yml'
以下示例配置包括文件名以 bundle
开头并以 .yml
结尾的所有文件。 这些文件与捆绑配置文件位于同一文件夹中:
include:
- 'bundle*.yml'
脚本
该 scripts
设置指定可以使用 bundle run
.. 映射中的每个 scripts
命名脚本都包含包含包含命令的内容。 例如:
scripts:
my_script:
content: uv run pytest -m ${bundle.target}
有关详细信息,请参阅 “执行脚本”。
同步
通过 sync
映射,可以配置哪些文件属于捆绑部署的一部分。
包含和排除
include
映射中的 exclude
和 sync
映射指定要包含在捆绑部署中或从捆绑部署中排除的文件或文件夹的列表,具体取决于以下规则:
- 根据捆绑包根目录的
.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
那么,my_package/dist
文件夹中文件扩展名为 *.whl
的所有文件将包含在内。
my_package/dist
文件夹中的任何其他文件不会包含在内。
但是,如果捆绑包配置文件还包含以下 exclude
映射:
sync:
include:
- my_package/dist/*.whl
exclude:
- my_package/dist/delete-me.whl
那么,my_package/dist
文件夹中文件扩展名为 *.whl
的所有文件(名称为 delete-me.whl
的文件除外)将包含在内。
my_package/dist
文件夹中的任何其他文件也不会包含在内。
还可以在特定目标的 sync
映射中声明 targets
映射。 目标中声明的任何 sync
映射将与任何顶级 sync
映射声明合并。 例如,在前面的示例中,include
级别的以下 targets
映射将与顶级 include
映射的 sync
映射合并:
targets:
dev:
sync:
include:
- my_package/dist/delete-me.whl
路径
映射 sync
可以包含一个 paths
映射,用于指定要同步到工作区的本地路径。 通过 paths
映射,可以跨捆绑包共享通用文件,并可用于同步位于捆绑包根目录之外的文件。 (捆绑包根目录是 databricks.yml 文件的位置。)如果单个存储库托管多个捆绑包,并且想要共享库、代码文件或配置,这尤其有用。
指定的路径必须与设置 paths
映射的文件夹上的文件和目录相对。 如果一个或多个路径值遍历目录到捆绑包根目录的上级目录,则会动态确定根路径,以确保文件夹结构保持不变。 例如,如果捆绑包根目录文件夹名为 my_bundle
,则 databricks.yml
中的此配置将同步位于捆绑包根目录上一级的 common
文件夹和捆绑包根目录本身:
sync:
paths:
- ../common
- .
部署此捆绑包会在工作区中产生以下文件夹结构:
common/
common_file.txt
my_bundle/
databricks.yml
src/
...
项目
顶级 artifacts
映射指定在捆绑包部署期间自动生成的一个或多个项目,这些项目稍后可在捆绑包运行中使用。 每个子项目都支持以下映射:
-
type
是生成 Python wheel 所必需的。 若要在部署之前生成 Python wheel 文件,请将该文件设置为whl
。 若要生成其他项目,无需指定此设置。 -
path
是可选路径。 路径相对于捆绑配置文件的位置。 对于 Python 滚轮生成,它是 Python 滚轮文件文件setup.py
的路径。 如果未包含path
,Databricks CLI 会尝试在打包文件的根目录中查找 Python wheel 文件的setup.py
文件。 -
files
是一个可选映射,其中包含子source
映射,可用于指定生成的项目。 路径相对于捆绑配置文件的位置。 -
build
是部署前要在本地运行的一组可选非默认生成命令。 对于 Python wheel 生成,Databricks CLI 假定它可以找到 Pythonwheel
包的本地安装来运行生成,并且在每个捆绑包部署期间默认运行命令python setup.py bdist_wheel
。 要指定多个构建命令,请使用双与号 (&&
) 字符分隔每个命令。 -
dynamic_version
使捆绑包能够根据 wheel 文件的时间戳来更新 wheel 版本。 然后,新代码就可以在无需更新setup.py
或pyproject.toml
版本的情况下部署。 仅当type
设置为whl
时,该设置才有效。
以下示例配置使用诗歌生成滚轮。 有关用于 artifacts
生成滚轮的完整示例捆绑包,请参阅 使用 Databricks 资产捆绑包生成 Python 滚轮文件。
artifacts:
default:
type: whl
build: poetry build
path: .
有关生成 JAR 并将其上传到 Unity 目录的示例配置,请参阅将 JAR 文件上传到 Unity 目录 的捆绑包。
提示
可以按照在 Databricks 资源捆绑包中定义项目设置中所述,定义、组合和替代捆绑包中项目的设置。
变量
捆绑包设置文件可能包含一个顶级 variables
映射,其中定义了自定义变量。 对于每个变量,请设置可选说明、默认值、自定义变量是否为复杂类型、用于检索 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>
注意
除非 string
设置为 type
,否则变量假定为类型 complex
。 请参阅定义复杂变量。
若要在捆绑包配置中引用自定义变量,请使用替换 ${var.<variable_name>}
。
有关自定义变量和替换的详细信息,请参阅 Databricks 资产捆绑包中的替换和变量。
工作区
捆绑包配置文件只能包含一个顶级 workspace
映射,该映射指定要使用的任何非默认 Azure Databricks 工作区设置。
重要
有效的 Databricks 工作区路径开头为 /Workspace
,但还支持 /Volumes
(适用于工件)。 自定义工作区路径会自动添加 /Workspace
前缀;因此,如果在自定义路径中使用任何工作区路径替换(如 ${workspace.file_path}
),则不需要在路径前添加 /Workspace
。
根路径
此 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}
的默认路径,该路径使用替换。
工件路径
此 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
映射默认为 ${workspace.root}/state
的默认路径,表示工作区中用于存储有关部署的 Terraform 状态信息的路径。
其他工作区映射
workspace
映射还可以包含以下可选映射,以指定要使用的 Azure Databricks 身份验证机制。 如果未在此 workspace
映射中指定这些可选映射,必须在 workspace
映射中将其指定为顶级目标映射中一个或多个目标的子级。
profile
映射(或使用 Databricks CLI 运行捆绑包验证、部署、运行和销毁命令时使用--profile
或-p
选项)指定与此工作区一起用于 Azure Databricks 身份验证的配置文件的名称。 此配置文件映射到在设置 Databricks CLI 时创建的配置文件。注意
Databricks 建议使用
host
映射(或使用 Databricks CLI 运行捆绑包验证、部署、运行和销毁命令时使用--profile
或-p
选项)代替profile
映射,因为这样可以使捆绑包配置文件更易于移植。 设置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 授权对 Azure Databricks 资源进行无须人工干预的访问。注意
不能在捆绑包配置文件中指定 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
选项)。 查看 MS Entra 服务主体身份验证。注意
不能在捆绑包配置文件中指定 Azure 客户端密码值。 应该设置本地环境变量
ARM_CLIENT_SECRET
。 或者,可以将azure_client_secret
值添加到配置文件,然后使用profile
映射指定配置文件的名称(或者在通过 Databricks CLI 运行捆绑包验证、部署、运行和销毁命令时使用--profile
或-p
选项)。对于 Azure 托管标识身份验证,将使用映射
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 托管标识身份验证。azure_environment
映射为一组特定的 API 终结点指定 Azure 环境类型(例如 Public、UsGov、China 和 Germany)。 默认值为PUBLIC
。 也可以在本地环境变量ARM_ENVIRONMENT
中设置此值。 或者,可以将azure_environment
值添加到配置文件,然后使用profile
映射指定配置文件的名称(或者在通过 Databricks CLI 运行捆绑包验证、部署、运行和销毁命令时使用--profile
或-p
选项)。azure_login_app_id
映射不可操作,保留供内部使用。auth_type
映射指定要使用的 Azure Databricks 身份验证类型,尤其是在 Databricks CLI 推断出意外身份验证类型的情况下。 请参阅 授权访问 Azure Databricks 资源。
权限
顶级 permissions
映射指定要应用于捆绑包中定义的所有资源的一个或多个权限级别。 如果要将权限应用于特定资源,请参阅定义特定资源的权限。
允许的顶级权限级别是 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
资源
resources
映射指定了捆绑包使用的 Azure Databricks 资源的相关信息。
此 resources
映射可以显示为顶级映射,也可以是顶级目标映射中一个或多个目标的子级,并且包括零个或一个受支持的资源类型。 每个资源类型映射都包含一个或多个单独的资源声明,其中每个声明必须具有唯一的名称。 这些单独的资源声明使用相应对象的创建操作的请求有效负载(用 YAML 表示)来定义资源。 资源支持的属性是相应对象支持的字段。
Databricks REST API 参考中介绍了创建操作的请求有效负载,databricks bundle schema
命令将输出所有受支持的对象架构。 此外,如果在捆绑包配置文件中发现未知资源属性,databricks bundle validate
命令将返回警告。
以下示例配置定义了一个作业资源。
resources:
jobs:
hello-job:
name: hello-job
tasks:
- task_key: hello-task
existing_cluster_id: 1234-567890-abcde123
notebook_task:
notebook_path: ./hello.py
有关捆绑包中支持的资源以及常见配置和示例的详细信息,请参阅 Databricks 资产捆绑包资源和捆绑包配置示例。
目标
targets
映射指定运行 Azure Databricks 工作流的一个或多个上下文。 每个目标是项目、Azure Databricks 工作区设置和 Azure Databricks 作业或管道详细信息的唯一集合。
targets
映射由一个或多个目标映射组成,每个目标映射必须具有唯一的编程(或逻辑)名称。
此 targets
映射是可选的,但强烈建议使用。 如果指定它,它只能显示为顶级映射。
如果未在 映射中指定顶级工作区、项目和targets
映射中的设置,则将使用它们,但任何冲突的设置都将被目标内的设置覆盖。
目标还可以替代任何顶级变量的值。
默认
若要为捆绑包命令指定目标默认值,请将 default
映射设置为 true
。 例如,名为 dev
的目标是默认目标:
targets:
dev:
default: true
如果未配置默认目标,或者想要在特定目标内验证、部署和运行作业或管道,请使用捆绑包命令的 -t
选项。
以下命令在 my_job
和 dev
目标中验证、部署和运行 prod
:
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
以下示例声明两个目标。 第一个目标具有名称 dev
,是未为捆绑包命令指定目标时使用的默认目标。 第二个目标具有名称 prod
,仅在为捆绑包命令指定此目标时才使用。
targets:
dev:
default: true
prod:
workspace:
host: https://<production-workspace-url>
模式和预设
为了方便开发和 CI/CD 最佳做法,Databricks 资产捆绑包为目标提供了部署模式,其为预生产和生产工作流设置默认行为。 一些行为也是可配置的。 有关详细信息,请参阅 Databricks 资产捆绑包部署模式。
提示
若要为捆绑包设置运行标识,还可以为每个目标指定 run_as
,如指定 Databricks 资产捆绑包工作流的运行标识中所述。
若要指定将目标视为开发目标,请添加 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
,则将取消暂停计划。