Databricks 资产捆绑包项目模板

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

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

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

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 提供以下默认的捆绑包模板：

自定义捆绑模板

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

模板项目结构

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

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

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

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

模板架构

自定义捆绑包模板项目必须包含 databricks_template_schema.json [JSON 文件]（项目根目录中的 https://json-schema.org/specification.html）。 此文件定义运行 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}}）访问变量的值。

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

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

YAML 配置模板

自定义捆绑包模板应包含捆绑模板项目中 template 文件夹中的 databricks.yml.tmpl 文件，该文件用于创建捆绑项目 databricks.yml。 使用基本配置模板 YAML 填充此模板文件。

以下示例配置模板用于 databricks.yml 和关联的 *_job.yml，它们设定了捆绑包名称和两个目标环境，并且定义了一个用于运行捆绑包中笔记本的作业，适用于使用此模板创建的捆绑包。 这些配置模板利用捆绑包替换和捆绑包模板帮助程序。 请参阅捆绑包替换和捆绑包模板帮助程序。

# 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 -}}

# {{.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 模板。

若要定义自己的变量，请在模板项目的 library 文件夹中创建模板文件，并使用 Go 模板化语法定义变量。 例如，library/variables.tmpl 文件的以下内容定义变量 cli_version 和 model_name。 使用此模板初始化捆绑包时，将使用模板架构文件中定义的 input_project_name 字段构造 model_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 创建和维护的其他模板。 请参阅 GitHub 中的 捆绑包示例存储库。
• 若要将 MLOps Stacks 与 Databricks 资产捆绑包模板配合使用，请参阅适用于 MLOps Stacks 的 Databricks 资产捆绑包。
• 详细了解 Go 包模板化。 请参阅 Go 包模板 文档。