Databricks 资产捆绑包模板

本文介绍 Databricks 资产捆绑包模板的语法，这些模板适用于 Databricks CLI 0.218.0 及更高版本。 捆绑包支持以编程方式管理 Azure Databricks 工作流。 请参阅什么是 Databricks 资产捆绑包？

捆绑包模板使用户可以建立文件夹结构、生成步骤和任务、测试和其他开发环境部署管道中常见的 DevOps 基础结构即代码 (IaC) 属性，从而以一致、可重复的方式创建捆绑包。

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

捆绑包模板定义将创建的捆绑包的目录结构，其中包括databricks.yml.tmpl配置文件模板以及包含用户提示变量的databricks_template_schema.json文件。

基于模板创建捆绑包

本部分介绍如何使用捆绑模板，即 Azure Databricks 默认捆绑模板或自定义捆绑模板。

使用默认捆绑包模板

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

databricks bundle init default-python

如果未指定默认模板，bundle init命令会显示一组可用的模板，可从中进行选择。

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

使用自定义捆绑包模板

若要使用 Azure Databricks 默认捆绑模板以外的捆绑模板，请将模板的本地路径或远程 URL 传递到 Databricks CLI bundle init 命令。

例如，以下命令使用在自定义捆绑包模板教程中创建的dab-container-template模板：

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

创建捆绑包模板

捆绑包模板使用 Go 包模板化语法。 请参阅 Go 包模板 文档。

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

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

可以选择将子文件夹和文件添加到要镜像到模板创建的捆绑包中的template文件夹中。

定义用户提示变量

生成基本捆绑包模板的第一步是在项目根目录中创建模板项目文件夹和名为databricks_template_schema.json的文件。 此文件包含用户在使用模板通过bundle init创建捆绑包时为其提供输入值的变量。 此文件的格式遵循 JSON 架构规范。

mkdir basic-bundle-template
touch basic-bundle-template/databricks_template_schema.json

将以下内容添加到databricks_template_schema.json文件，然后保存文件：

{
   "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."
}

在此文件中：

• project_name是唯一的输入变量名称。
• 如果用户未使用--config-file作为bundle init命令的一部分提供某个值，或者值在命令提示符中被用户重写，则default是可选默认值。
• 如果用户未使用--config-file作为bundle init命令的一部分提供某个值，则description是与输入变量关联的用户提示。
• 如果用户未使用--config-file作为bundle init命令的一部分提供某个值，则order是每个用户提示显示的可选顺序。 如果未提供order，则用户提示按在架构中的列出顺序显示。
• success_message 是成功创建项目时显示的可选消息。

生成文件夹结构

接下来，创建所需的template文件夹，并在其中生成文件夹结构。 此结构将由使用此模板创建的捆绑包进行镜像。 此外，请将要包含的任何文件放入这些文件夹中。 此基本捆绑包模板将文件存储在src文件夹中，并包括一个简单的笔记本。

mkdir -p basic-bundle-template/template/src
touch basic-bundle-template/template/src/simple_notebook.ipynb

将以下内容添加到simple_notebook.ipynb文件中：

print("Hello World!")

填充配置模板文件

现在，在template文件夹中创建所需的databricks.yml.tmpl文件：

touch basic-bundle-template/template/databricks.yml.tmpl

使用基本配置模板 YAML 填充此文件。 此配置模板建立捆绑包名称、使用指定笔记本文件的一个作业，以及使用此模板创建的捆绑包的两个目标环境。 它还利用捆绑包替换（强烈推荐）。 请参阅捆绑包替换。

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

bundle:
  name: {{.project_name}}

# 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

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

测试捆绑包模板

最后，测试模板。 新建捆绑包项目文件夹，然后使用 Databricks CLI 通过模板初始化新捆绑包：

mkdir my-test-bundle
cd my-test-bundle
databricks bundle init ../basic-bundle-template

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

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

my-test-bundle
   ├── databricks.yml
   └── src
      └── simple_notebook.ipynb

databricks.yml 文件现已自定义：

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

bundle:
  name: my-test-bundle

# 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

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

共享模板

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

后续步骤

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