Databricks 资产捆绑包项目模板

Databricks 资产捆绑包将 Databricks 资源（如作业、管道和笔记本）描述为源文件，使你能够包括元数据以及这些源文件来预配基础结构和其他资源，并提供项目的端到端定义，所有资源都打包为单个可部署项目。 请参阅什么是 Databricks 资产捆绑包？。

捆绑模板使用户可以通过建立文件夹结构、生成步骤和任务、测试和其他跨部署管道通用的 DevOps 基础结构即代码 （IaC） 属性，以一致、可重复的方式创建捆绑包。

例如，如果在安装时定期运行需要具有耗时编译步骤的自定义包的作业，则可以通过创建指定自定义容器环境的捆绑模板来加快开发循环。

Databricks 提供一组 默认捆绑模板，但也可以创建 自定义捆绑模板。 然后，用户可以使用 bundle init 命令初始化捆绑包，并指定默认模板或自定义模板。

使用模板创建捆绑包

若要使用 Azure Databricks 捆绑模板创建捆绑包，请使用 Databricks CLIbundle init 命令，并指定要使用的模板的名称。 例如，以下命令使用默认的 Python 捆绑包模板创建捆绑包：

databricks bundle init default-python

若要使用自定义捆绑包模板，请将模板的本地路径或远程 URL 传递给 Databricks CLIbundle init 命令。

例如，以下命令使用在dab-container-template中创建的 模板：

databricks bundle init /projects/my-custom-bundle-templates/dab-container-template

如果未指定模板，则 bundle init 命令会显示一个可供选择的默认模板集。

默认捆绑模板

Azure Databricks 提供以下默认的捆绑包模板：

模板	说明
default-python	将 Python 与 Databricks 配合使用的模板。 此模板创建包含作业和 ETL 管道的捆绑包。 请参阅默认 python。
default-sql	将 SQL 与 Databricks 配合使用的模板。 此模板包含配置文件，用于定义在 SQL 仓库上运行 SQL 查询的作业。 请参阅default-sql。
dbt-sql	一个模板，它利用 dbt-core 进行本地开发，利用捆绑包进行部署。 此模板包含配置和一个配置文件，其中配置用于定义具有 dbt 任务的作业，而文件用于定义已部署的 dbt 作业的 dbt 配置文件。 请参阅dbt-sql。
mlops-stacks	用于启动新 MLOps Stacks 项目的高级完整堆栈模板。 请参阅mlops-stacks和适用于 MLOps Stacks 的 Databricks 资产捆绑包。

自定义捆绑模板

捆绑模板使用 Go 包模板化语法，为可以创建的自定义捆绑模板提供灵活性。 请参阅 Go 包模板 文档。

模板项目结构

捆绑模板项目至少必须具有：

• 项目根目录下的 databricks_template_schema.json 文件，用于定义捆绑包项目名称的一个用户提示属性。 请参阅 模板架构。
• 位于databricks.yml.tmpl文件夹中的template文件，用于定义使用模板创建的任何捆绑包的配置。 如果databricks.yml.tmpl文件引用任何其他*.yml.tmpl配置模板，请在include映射中指定这些模板的位置。 请参阅 配置模板。

此外，捆绑模板项目的文件夹结构和包含的文件 template 文件夹由使用模板创建的捆绑包进行镜像。 例如，如果希望模板在 src 文件夹中生成一个包含简单笔记本的捆绑包，以及一个在 resources 文件夹中运行笔记本的作业定义，则可以按如下方式组织你的模板项目：

basic-bundle-template
  ├── databricks_template_schema.json
  └── template
      └── {{.project_name}}
          ├── databricks.yml.tmpl
          ├── resources
          │   └── {{.project_name}}_job.yml.tmpl
          └── src
              └── simple_notebook.ipynb

提示

此捆绑模板中的项目文件夹名称和作业定义文件的名称使用模板变量。 有关模板帮助程序和变量的信息，请参阅 模板帮助器和变量。

模板架构

自定义捆绑模板项目必须包含项目根目录中的 databricks_template_schema.jsonJSON 文件 。 此文件定义运行 bundle init 命令时 Databricks CLI 使用的字段，例如提示文本。

以下基本 databricks_template_schema.json 文件定义捆绑项目的输入变量 project_name，其中包括提示消息和默认值。 然后，它为捆绑项目初始化定义成功消息，该消息使用消息中的输入变量值。

{
  "properties": {
    "project_name": {
      "type": "string",
      "default": "basic_bundle",
      "description": "What is the name of the bundle you want to create?",
      "order": 1
    }
  },
  "success_message": "\nYour bundle '{{.project_name}}' has been created."
}

模板架构字段

databricks_template_schema.json 文件支持定义输入变量，以便通过 properties 字段从用户那里收集信息，同时提供其他字段以定制初始化过程。

输入变量在模板架构的 properties 字段中定义。 每个输入变量定义在捆绑初始化期间向用户显示提示所需的元数据。 然后，可以使用模板变量语法（如 {{.project_name}}）访问变量的值。

还可以设置某些字段的值以自定义捆绑包初始化过程。

下表中列出了支持的架构字段。

架构字段	说明
properties	捆绑包模板输入变量定义。 Databricks 建议至少定义一个输入变量，该变量是捆绑项目的名称。
properties.<variable_name>	输入变量的名称。
properties.<variable_name>.default	如果用户在使用 --config-file 命令时未通过 bundle init 提供值，或者在系统提示时未在命令行处提供值，则使用该默认值。
properties.<variable_name>.description	与输入变量关联的用户提示消息。
properties.<variable_name>.enum	属性的可能值列表，例如 "enum": ["azure", "aws", "gcp"]。 如果定义了此字段，Databricks CLI 会在命令行的列表中显示值，以提示用户选择值。
properties.<variable_name>.order	一个整数，用于定义输入属性的相对顺序。 这将控制在命令行中显示这些输入变量提示的顺序。
properties.<variable_name>.pattern	用于验证用户输入的正则表达式模式，例如 "pattern": "^[^ .\\\\/]{3,}$"。 有关支持的正则表达式语法，请参阅 https://github.com/google/re2/wiki/Syntax。
properties.<variable_name>.pattern_match_failure_message	如果用户输入的值与指定的模式不匹配，则向用户显示的消息，例如，Project name must be at least 3 characters long and cannot contain the following characters: \"\\\", \"/\", \" \" and \".\"."。
properties.<variable_name>.skip_prompt_if	如果配置已满足此架构，请跳过提示输入变量。 在这种情况下，将改用属性的默认值。 有关示例，请参阅 mlops-stacks 模板。 仅支持 const 比较。
properties.<variable_name>.skip_prompt_if.properties.<previous_variable_name>.const	如果 <previous_variable_name> 的值与 skip_prompt_if中配置的常量匹配，则会跳过 <variable_name> 提示。
welcome_message	提示用户输入之前要输出的第一条消息。
success_message	成功初始化模板后要打印的消息。
min_databricks_cli_version	模板需要的此 Databricks CLI 的最低 SemVer 版本。 如果 CLI 版本小于此版本，则 databricks bundle init 失败。
version	保留以供将来使用。 架构的版本。 这用于确定架构是否与当前 CLI 版本兼容。

配置模板

自定义捆绑包模板应包含一个databricks.yml.tmpl文件，该文件位于捆绑模板项目中的template文件夹内，用于创建捆绑项目的databricks.yml配置文件。 可以在文件夹中为资源的配置文件创建 resources 模板。 使用配置模板 YAML 填充这些模板文件。

下面的简单示例配置模板为databricks.yml和关联的*_job.yml定义了捆绑包名称和两个目标环境，并为使用此模板创建的捆绑包定义一个运行捆绑包中笔记本的作业。 这些配置模板利用 捆绑替换 和 捆绑模板助手。

template/{{.project_name}}/databricks.yml.tmpl:

# databricks.yml
# This is the configuration for the Databricks Asset Bundle {{.project_name}}.

bundle:
  name: {{.project_name}}

include:
  - resources/*.yml

targets:
  # The deployment targets. See https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html
  dev:
    mode: development
    default: true
    workspace:
      host: {{workspace_host}}

  prod:
    mode: production
    workspace:
      host: {{workspace_host}}
      root_path: /Shared/.bundle/prod/${bundle.name}
    {{- if not is_service_principal}}
    run_as:
      # This runs as {{user_name}} in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: {{user_name}}
    {{end -}}

template/{{.project_name}}/resources/{{.project_name}}_job.yml.tmpl:

# {{.project_name}}_job.yml
# The main job for {{.project_name}}

resources:
    jobs:
        {{.project_name}}_job:
        name: {{.project_name}}_job
        tasks:
            - task_key: notebook_task
            job_cluster_key: job_cluster
            notebook_task:
                notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
            new_cluster:
                node_type_id: i3.xlarge
                spark_version: 13.3.x-scala2.12

模板帮助器和变量

模板帮助程序是由 Databricks 提供的函数，可在模板文件中使用该函数在运行时获取用户特定的信息或与模板引擎交互。 还可以定义自己的模板变量。

以下模板帮助程序可用于 Databricks 捆绑模板项目。 有关使用 Go 模板和变量的信息，请参阅 Go 模板。

助手	说明
{{url}}	https://pkg.go.dev/net/url#Parse的别名。 这允许使用 url.URL 的所有方法。
{{regexp}}	https://pkg.go.dev/regexp#Compile的别名。 这允许使用 regexp.Regexp 的所有方法。
{{random_int}}	以 int 形式返回半开放间隔（0，n）中的非负伪随机数。
{{uuid}}	以字符串形式返回 UUID，它是 RFC 4122 中定义的 128 位（16 字节）通用唯一 IDentifier。此 ID 在模板执行期间稳定，可用于填充模板作者databricks.yml中的 bundle.uuid 字段。
{{bundle_uuid}}	捆绑包的唯一 ID。 此函数的多个调用将返回相同的 UUID。
{{pair}}	键/值对。 它与 map 帮助程序一起使用，以生成要在模板中使用的映射。
{{map}}	将对列表转换为映射对象。 这可用于将多个对象传递给库目录中定义的模板。 由于用于调用模板的 Go 文本模板语法仅允许指定单个参数，因此此函数可用于解决该限制。 例如，在以下行中，{{template "my_template" (map (pair "foo" $arg1) (pair "bar" $arg2))}}、$arg1 和 $arg2 可以从 my_template 内部引用为 .foo 和 .bar。
{{smallest_node_type}}	返回最小的节点类型。
{{path_separator}}	操作系统的路径分隔符字符。 这是 Unix 系统的 / 和 Windows 系统的 \。
{{workspace_host}}	用户当前已向其进行身份验证的工作区主机 URL。
{{user_name}}	初始化模板的用户的完整名称。
{{short_name}}	初始化模板的用户的短名称。
{{default_catalog}}	返回默认工作区目录。 如果没有默认值，或者未启用 Unity 目录，则返回一个空字符串。
{{is_service_principal}}	当前用户是否为服务主体。
{{ skip <glob-pattern-relative-to-current-directory> }}	使模板引擎跳过生成与输入 glob 模式匹配的所有文件和目录。 有关示例，请参阅 mlops-stacks 模板。

自定义模板助手

若要定义自己的模板帮助程序，请在 library 模板项目的文件夹中创建模板文件，并使用 Go 模板化语法定义帮助程序。 例如，library/variables.tmpl 文件的以下内容定义变量 cli_version 和 model_name。 使用此模板初始化捆绑包时，将使用模板架构文件中定义的 model_name 字段构造 input_project_name 变量的值。 此字段值的值是提示后的用户输入。

{{ define `cli_version` -}}
    v0.240.0
{{- end }}

{{ define `model_name` -}}
    {{ .input_project_name }}-model
{{- end }}

若要查看完整的示例，请参阅 mlops-stacks 模板变量文件。

测试组合模板

最后，请确保测试模板。 例如，使用 Databricks CLI 使用前面部分定义的模板初始化新捆绑包：

databricks bundle init basic-bundle-template

对于“What is your bundle project name?”提示，请键入 my_test_bundle。

创建测试捆绑包后，会输出架构文件中的成功消息。 如果检查my_test_bundle文件夹的内容，应看到以下内容：

my_test_bundle
   ├── databricks.yml
   ├── resources
   │  └── my_test_bundle_job.yml
   └── src
      └── simple_notebook.ipynb

databricks.yml 文件和作业现已被自定义。

# databricks.yml
# This is the configuration for the Databricks Asset Bundle my-test-bundle.

bundle:
  name: my_test_bundle

include:
  - resources/*.yml

targets:
  # The 'dev' target, used for development purposes. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#development-mode)
  dev:
    mode: development
    default: true
    workspace:
      host: https://my-host.cloud.databricks.com

  # The 'prod' target, used for production deployment. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#production-mode)
  prod:
    mode: production
    workspace:
      host: https://my-host.cloud.databricks.com
      root_path: /Shared/.bundle/prod/${bundle.name}
    run_as:
      # This runs as someone@example.com in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: someone@example.com

# my_test_bundle_job.yml
# The main job for my_test_bundle

resources:
    jobs:
        my_test_bundle_job:
        name: my_test_bundle_job
        tasks:
            - task_key: notebook_task
                job_cluster_key: job_cluster
                notebook_task:
                    notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
                new_cluster:
                    node_type_id: i3.xlarge
                    spark_version: 13.3.x-scala2.12

共享模板

如果要与他人共享此捆绑包模板，可以使用 Git 支持且用户有权访问的任何提供程序将其存储在版本控制中。 若要使用 Git URL 运行 bundle init 命令，请确保 databricks_template_schema.json 文件位于相对于该 Git URL 的根位置。

提示

可以将文件放在 databricks_template_schema.json 其他文件夹中，相对于捆绑包的根目录。 然后可以使用 bundle init 命令的 --template-dir 选项来引用包含该 databricks_template_schema.json 文件的文件夹。

后续步骤

• 浏览由 Databricks 创建和维护的其他模板。 请参阅 GitHub 中的 捆绑包示例存储库。
• 若要将 MLOps Stacks 与 Databricks 资产捆绑包模板配合使用，请参阅适用于 MLOps Stacks 的 Databricks 资产捆绑包。
• 详细了解 Go 包模板化。 请参阅 Go 包模板 文档。