计算策略参考

项目
04/19/2024

本文是计算策略定义的参考。文章包括可用策略属性和限制类型的参考。还有可以参考常见用例的示例策略。

什么是策略定义？

策略定义是用 JSON 表示的单个策略规则。定义可以将规则添加到使用群集 API 控制的任何属性。例如，这些定义设置默认的自动终止时间，禁止用户使用池，并强制使用 Photon：

{
   "autotermination_minutes" : {
    "type" : "unlimited",
    "defaultValue" : 4320,
    "isOptional" : true
  },
  "instance_pool_id": {
    "type": "forbidden",
    "hidden": true
  },
  "runtime_engine": {
    "type": "fixed",
    "value": "PHOTON",
    "hidden": true
  }
}

每个属性只能有一个限制。属性的路径反映 API 属性名称。对于嵌套属性，路径使用点来连接嵌套属性名称。策略定义中未定义的属性不会受到限制。

支持的属性

策略支持使用群集 API控制的所有属性。可以针对属性设置的限制类型可能因其类型和与 UI 元素的关系而异。不能使用策略来定义计算权限。

还可以使用策略设置每小时的最大 DBU 数和群集类型。请参阅虚拟属性路径。

下表列出了支持的策略属性路径：

属性路径	类型	说明
`autoscale.max_workers`	可选数值	隐藏后，从 UI 中删除“最大辅助角色数目”字段。
`autoscale.min_workers`	可选数值	隐藏后，从 UI 中删除“最小辅助角色数目”字段。
`autotermination_minutes`	number	值 0 表示没有自动终止。隐藏后，从 UI 中删除自动终止复选框和值输入。
`azure_attributes.availability`	string	控制计算是使用按需实例还是现成实例（`ON_DEMAND_AZURE` 或 `SPOT_WITH_FALLBACK_AZURE`）。
`azure_attributes.first_on_demand`	数字	控制要放置在按需实例上的节点数。
`azure_attributes.spot_bid_max_price`	number	控制 Azure 现成实例的最高价格。
`cluster_log_conf.path`	string	日志文件的目标 URL。
`cluster_log_conf.type`	string	日志目标的类型。唯一可接受的值是 `DBFS`。
`cluster_name`	string	群集名称。
`custom_tags.*`	字符串	通过追加标记名来控制特定的标记值，例如：`custom_tags.<mytag>`。
`data_security_mode`	string	设置群集的访问模式。 Unity Catalog 需要 `SINGLE_USER` 或 `USER_ISOLATION`（UI 中的共享访问模式）。 `NONE` 值意味着未启用任何安全功能。
`docker_image.basic_auth.password`	string	用于 Databricks 容器服务映像基本身份验证的密码。
`docker_image.basic_auth.username`	字符串	用于 Databricks 容器服务映像基本身份验证的用户名。
`docker_image.url`	字符串	控制 Databricks 容器服务映像 URL。隐藏后，从 UI 中删除“Databricks 容器服务”部分。
`driver_node_type_id`	可选字符串	隐藏后，从 UI 中删除驱动器节点类型选择。
`enable_local_disk_encryption`	boolean	设置为 `true` 以启用，或设置为 `false` 禁用对本地附加到群集的磁盘进行加密（通过 API 指定）。
`init_scripts..workspace.destination` `init_scripts..volumes.destination` `init_scripts..abfss.destination` `init_scripts..file.destination`	string	`*` 是指属性数组中初始化脚本的索引。请参阅编写数组属性的策略。
`instance_pool_id`	string	控制工作器节点使用的池（如果还定义了 `driver_instance_pool_id`，或者对于所有其他群集节点）。如果为工作器节点使用池，则也必须为驱动程序节点使用池。隐藏后，从 UI 中删除池选择。
`driver_instance_pool_id`	string	如果已指定，则为驱动程序节点配置不同于工作器节点的池。如果未指定，则会继承 `instance_pool_id`。如果为工作器节点使用池，则也必须为驱动程序节点使用池。如果已隐藏，则会从 UI 中删除驱动程序池选择。
`node_type_id`	string	隐藏后，从 UI 中删除工作器节点类型选择。
`num_workers`	可选数值	隐藏后，从 UI 中删除辅助角色数目规范。
`runtime_engine`	字符串	确定群集是否使用 Photon。可能的值为 `PHOTON` 或 `STANDARD`。
`single_user_name`	字符串	用于凭据直通单用户访问的用户名。
`spark_conf.*`	可选字符串	通过追加配置键名称来控制特定的配置值，例如：`spark_conf.spark.executor.memory`。
`spark_env_vars.*`	可选字符串	通过追加环境变量来控制特定 Spark 环境变量值，例如：`spark_env_vars.<environment variable name>`。
`spark_version`	string	通过 API 指定的 Spark 映像版本名称（Databricks Runtime）。还可以使用动态选择 Databricks Runtime 的特殊策略值。请参阅用于 Databricks Runtime 选择的特殊策略值。
`workload_type.clients.jobs`	boolean	定义计算资源是否可用于作业。请参阅防止计算与作业一起使用。
`workload_type.clients.notebooks`	boolean	定义计算资源是否可用于笔记本。请参阅防止计算与作业一起使用。

虚拟属性路径

此表包括策略支持的另外两个合成属性：

属性路径	类型	说明
`dbus_per_hour`	数字	表示资源每小时可以使用的最大 DBU 数的计算属性，包括驱动程序节点。此指标是在单个计算级别控制成本的直接方法。与范围限制配合使用。
`cluster_type`	string	表示可以创建的群集类型： * `all-purpose` 用于 Azure Databricks 通用计算 * `job` 用于作业计划程序创建的作业计算 * `dlt` 用于为 Delta Live Tables 管道创建的计算允许或阻止从策略创建指定类型的计算。如果不允许使用 `all-purpose` 值，则通用创建计算 UI 中不会显示该策略。如果不允许使用 `job` 值，则创建作业计算 UI 中不会显示该策略。

用于 Databricks Runtime 选择的特殊策略值

spark_version 属性支持根据当前支持的 Databricks Runtime 版本集动态映射到 Databricks Runtime 版本的特殊值。

可以在 spark_version 属性中使用以下值：

auto:latest：映射到最新的正式发布 Databricks Runtime 版本。
auto:latest-ml：映射到最新的 Databricks Runtime ML 版本。
auto:latest-lts：映射到最新的长期支持 (LTS) Databricks Runtime 版本。
auto:latest-lts-ml：映射到最新的 LTS Databricks Runtime ML 版本。
auto:prev-major：映射到第二新的正式发布 Databricks Runtime 版本。例如，如果 auto:latest 为 14.2，则 auto:prev-major 为 13.3。
auto:prev-major-ml：映射到第二新的正式发布 Databricks Runtime ML 版本。例如，如果 auto:latest 为 14.2，则 auto:prev-major 为 13.3。
auto:prev-lts：映射到第二新的 LTS Databricks Runtime 版本。例如，如果 auto:latest-lts 为 13.3，则 auto:prev-lts 为 12.2。
auto:prev-lts-ml：映射到第二新的 LTS Databricks Runtime ML 版本。例如，如果 auto:latest-lts 为 13.3，则 auto:prev-lts 为 12.2。

注意

使用这些值不会在发布新的运行时版本时自动更新计算。用户必须显式编辑计算才能更改 Databricks 运行时版本。

支持的策略类型

本部分包含每个可用策略类型的参考。有两种策略类型：固定策略和限制策略。

固定策略可防止用户对属性进行配置。固定策略的两种类型为：

固定策略
禁止的策略

限制策略会限制用户的属性配置选项。限制策略还允许设置默认值并使属性可选。请参阅其他限制策略字段。

限制策略的选项包括：

允许列表策略
阻止列表策略
正则表达式策略
范围策略
无限制策略

固定策略

固定策略将属性限制为指定值。数值和布尔值以外的属性值必须由字符串表示或必须可转换为字符串。

对于固定策略，还可以通过将 hidden 字段设置为 true 来隐藏 UI 中的属性。

interface FixedPolicy {
    type: "fixed";
    value: string | number | boolean;
    hidden?: boolean;
}

此示例策略修复了 Databricks Runtime 版本，并从用户的 UI 中隐藏字段：

{
  "spark_version": { "type": "fixed", "value": "auto:latest-lts", "hidden": true }
}

禁止策略

禁止策略可防止用户配置属性。禁止策略仅与可选属性兼容。

interface ForbiddenPolicy {
    type: "forbidden";
}

此策略禁止将池附加到工作器节点的计算。由于 driver_instance_pool_id 继承该策略，因此也禁止将池附加到驱动程序节点。

{
  "instance_pool_id": { "type": "forbidden" }
}

允许列表策略

允许列表策略指定用户在配置属性时可以选择的值列表。

interface AllowlistPolicy {
  type: "allowlist";
  values: (string | number | boolean)[];
  defaultValue?: string | number | boolean;
  isOptional?: boolean;
}

此允许列表示例允许用户在两个 Databricks Runtime 版本之间进行选择：

{
  "spark_version":  { "type": "allowlist", "values": [ "13.3.x-scala2.12", "12.2.x-scala2.12" ] }
}

阻止列表策略

阻止列表策略列出不允许的值。由于值必须完全匹配，因此当属性在值的表示方式上较为宽松时（例如允许前导空格和尾随空格），此策略可能无法达到预期效果。

interface BlocklistPolicy {
  type: "blocklist";
  values: (string | number | boolean)[];
  defaultValue?: string | number | boolean;
  isOptional?: boolean;
}

此示例阻止用户选择 7.3.x-scala2.12 作为 Databricks Runtime。

{
  "spark_version":  { "type": "blocklist", "values": [ "7.3.x-scala2.12" ] }
}

正则表达式策略

正则表达式策略将可用值限制为与正则表达式匹配的值。为了安全起见，请确保正则表达式锚定在字符串值的开头和结尾。

interface RegexPolicy {
  type: "regex";
  pattern: string;
  defaultValue?: string | number | boolean;
  isOptional?: boolean;
}

此示例限制用户可以选择的 Databricks Runtime 版本：

{
  "spark_version":  { "type": "regex", "pattern": "13\\.[3456].*" }
}

范围策略

范围策略使用 minValue 和 maxValue 字段将值限制为指定范围。该值必须是一个十进制数。数值限制必须表示为双浮点值。要指示缺少特定的限制，可以省略 minValue 或 maxValue。

interface RangePolicy {
  type: "range";
  minValue?: number;
  maxValue?: number;
  defaultValue?: string | number | boolean;
  isOptional?: boolean;
}

此示例将工作器的最大数量限制为 10：

{
  "num_workers":  { "type": "range", "maxValue": 10 }
}

无限制策略

无限制策略用于使属性成为必需或在 UI 中设置默认值。

interface UnlimitedPolicy {
  type: "unlimited";
  defaultValue?: string | number | boolean;
  isOptional?: boolean;
}

此示例将 COST_BUCKET 标记添加到计算：

{
  "custom_tags.COST_BUCKET":  { "type": "unlimited" }
}

为 Spark 配置变量设置默认值，同时允许省略（删除）该值：

{
  "spark_conf.spark.my.conf":  { "type": "unlimited", "isOptional": true, "defaultValue": "my_value" }
}

其他限制策略字段

对于限制策略类型，可以指定两个附加字段：

defaultValue - 在创建计算 UI 中自动填充的值。
isOptional - 属性上的限制策略会自动使其成为必需。要使属性成为可选项，请将 isOptional 字段设置为 true。

注意

默认值不会自动应用于使用群集 API 创建的计算。要使用该 API 应用默认值，请将参数 apply_policy_default_values 添加到计算定义并将其设置为 true。

此示例策略为工作器节点的池指定默认值 id1，但将此操作设为可选。创建计算时，可以选择其他池，也可以不使用任何池。如果策略中未定义 driver_instance_pool_id 或者在创建计算时，将为工作器节点和驱动程序节点使用同一个池。

{
  "instance_pool_id": { "type": "unlimited", "isOptional": true, "defaultValue": "id1" }
}

编写数组属性的策略

可以通过两种方式指定数组属性的策略：

对所有数组元素采用一般限制。这些限制在策略路径中使用 * 通配符。
对特定索引处的数组元素采用特定限制。这些限制在路径中使用数字。

例如，在数组属性 init_scripts 中，一般路径以 init_scripts.* 开头，特定路径以 init_scripts.<n> 开头，其中 <n> 是数组中的整数索引（从 0 开始）。可以将一般限制和特定限制结合起来，在这种情况下，一般限制适用于没有特定限制的每个数组元素。在每种情况下，只有一种政策限制适用。

以下部分展示了使用数组属性的常见示例。

需要特定于包含的条目

如果不指定顺序，则不能要求特定值。例如：

{
  "init_scripts.0.volumes.destination": {
    "type": "fixed",
    "value": "<required-script-1>"
  },
  "init_scripts.1.volumes.destination": {
    "type": "fixed",
    "value": "<required-script-2>"
  }
}

需要整个列表的固定值

{
  "init_scripts.0.volumes.destination": {
    "type": "fixed",
    "value": "<required-script-1>"
  },
  "init_scripts.*.volumes.destination": {
    "type": "forbidden"
  }
}

完全禁止使用

{
   "init_scripts.*.volumes.destination": {
    "type": "forbidden"
  }
}

允许遵循特定限制的条目

{
    "init_scripts.*.volumes.destination": {
    "type": "regex",
    "pattern": ".*<required-content>.*"
  }
}

修复 init 脚本的特定集

如果是 init_scripts 路径，数组可以包含多个结构中的一个，根据用例的不同，可能需要对这些结构的所有可能变体进行处理。例如，若要要求一组特定的初始化脚本，并且不允许其他版本的任何变体，可以使用以下模式：

{
  "init_scripts.0.volumes.destination": {
    "type": "fixed",
    "value": "<volume-paths>"
  },
  "init_scripts.1.volumes.destination": {
    "type": "fixed",
    "value": "<volume-paths>"
  },
  "init_scripts.*.workspace.destination": {
    "type": "forbidden"
  },
  "init_scripts.*.abfss.destination": {
    "type": "forbidden"
  },
  "init_scripts.*.file.destination": {
    "type": "forbidden"
  }
}

策略示例

本部分包括可用于创建你自己的策略的策略示例参考。还可以使用 Azure Databricks 提供的策略系列作为常见策略用例的模板。

常规计算策略
定义 Delta Live Tables 管道计算的限制
简单的中型策略
仅作业策略
外部元存储策略
防止计算与作业一起使用
删除自动缩放策略
自定义标记强制实施

常规计算策略

常规用途计算策略，用于指导用户并限制某些功能，同时要求使用标记、限制实例的最大数目并强制执行超时。

{
  "instance_pool_id": {
    "type": "forbidden",
    "hidden": true
  },
  "spark_version": {
    "type": "regex",
    "pattern": "12\\.[0-9]+\\.x-scala.*"
  },
  "node_type_id": {
    "type": "allowlist",
    "values": [
      "Standard_L4s",
      "Standard_L8s",
      "Standard_L16s"
    ],
    "defaultValue": "Standard_L16s_v2"
  },
  "driver_node_type_id": {
    "type": "fixed",
    "value": "Standard_L16s_v2",
    "hidden": true
  },
  "autoscale.min_workers": {
    "type": "fixed",
    "value": 1,
    "hidden": true
  },
  "autoscale.max_workers": {
    "type": "range",
    "maxValue": 25,
    "defaultValue": 5
  },
  "autotermination_minutes": {
    "type": "fixed",
    "value": 30,
    "hidden": true
  },
  "custom_tags.team": {
    "type": "fixed",
    "value": "product"
  }
}

定义 Delta Live Tables 管道计算的限制

注意

使用策略配置 Delta Live Tables 计算时，Databricks 建议对 default 和 maintenance 计算应用单个策略。

要为管道计算配置策略，请创建一个策略，将 cluster_type 字段设置为 dlt。以下示例为 Delta Live Tables 计算创建了一个最小策略：

{
  "cluster_type": {
    "type": "fixed",
    "value": "dlt"
  },
  "num_workers": {
    "type": "unlimited",
    "defaultValue": 3,
    "isOptional": true
  },
  "node_type_id": {
    "type": "unlimited",
    "isOptional": true
  },
  "spark_version": {
    "type": "unlimited",
    "hidden": true
  }
}

简单的中型策略

允许用户使用最小配置创建中型计算。创建时唯一的必需字段是计算名称，其余为固定字段和隐藏字段。

{
  "instance_pool_id": {
    "type": "forbidden",
    "hidden": true
  },
  "spark_conf.spark.databricks.cluster.profile": {
    "type": "forbidden",
    "hidden": true
  },
  "autoscale.min_workers": {
    "type": "fixed",
    "value": 1,
    "hidden": true
  },
  "autoscale.max_workers": {
    "type": "fixed",
    "value": 10,
    "hidden": true
  },
  "autotermination_minutes": {
    "type": "fixed",
    "value": 60,
    "hidden": true
  },
  "node_type_id": {
    "type": "fixed",
    "value": "Standard_L8s_v2",
    "hidden": true
  },
  "driver_node_type_id": {
    "type": "fixed",
    "value": "Standard_L8s_v2",
    "hidden": true
  },
  "spark_version": {
    "type": "fixed",
    "value": "auto:latest-ml",
    "hidden": true
  },
  "custom_tags.team": {
    "type": "fixed",
    "value": "product"
  }
}

仅作业策略

允许用户创建作业计算来运行作业。用户无法使用此策略创建通用计算。

{
  "cluster_type": {
    "type": "fixed",
    "value": "job"
  },
  "dbus_per_hour": {
    "type": "range",
    "maxValue": 100
  },
  "instance_pool_id": {
    "type": "forbidden",
    "hidden": true
  },
  "num_workers": {
    "type": "range",
    "minValue": 1
  },
  "node_type_id": {
    "type": "regex",
    "pattern": "Standard_[DLS]*[1-6]{1,2}_v[2,3]"
  },
  "driver_node_type_id": {
    "type": "regex",
    "pattern": "Standard_[DLS]*[1-6]{1,2}_v[2,3]"
  },
  "spark_version": {
    "type": "unlimited",
    "defaultValue": "auto:latest-lts"
  },
  "custom_tags.team": {
    "type": "fixed",
    "value": "product"
  }
}

外部元存储策略

允许用户创建已附加管理员定义的元存储的计算。这可用于允许用户创建自己的计算，且无需其他配置。

{
  "spark_conf.spark.hadoop.javax.jdo.option.ConnectionURL": {
      "type": "fixed",
      "value": "jdbc:sqlserver://<jdbc-url>"
  },
  "spark_conf.spark.hadoop.javax.jdo.option.ConnectionDriverName": {
      "type": "fixed",
      "value": "com.microsoft.sqlserver.jdbc.SQLServerDriver"
  },
  "spark_conf.spark.databricks.delta.preview.enabled": {
      "type": "fixed",
      "value": "true"
  },
  "spark_conf.spark.hadoop.javax.jdo.option.ConnectionUserName": {
      "type": "fixed",
      "value": "<metastore-user>"
  },
  "spark_conf.spark.hadoop.javax.jdo.option.ConnectionPassword": {
      "type": "fixed",
      "value": "<metastore-password>"
  }
}

防止计算与作业一起使用

此策略可防止用户使用计算来运行作业。用户只能将计算与笔记本一起使用。

{
  "workload_type.clients.notebooks": {
    "type": "fixed",
    "value": true
  },
  "workload_type.clients.jobs": {
    "type": "fixed",
    "value": false
  }
}

删除自动缩放策略

此策略禁用自动缩放，并允许用户设置给定范围内的工作器数。

{
  "num_workers": {
  "type": "range",
  "maxValue": 25,
  "minValue": 1,
  "defaultValue": 5
  }
}

自定义标记强制实施

要向策略添加计算标记规则，请使用 custom_tags.<tag-name> 属性。

例如，使用此策略的任何用户都需要使用 9999、9921 或 9531 填充 COST_CENTER 标记才能启动计算：

{"custom_tags.COST_CENTER": {"type":"allowlist", "values":["9999", "9921", "9531" ]}}