共用方式為

計算原則參考

  • 發行項

本文是計算原則定義的參考。 這些文章包含了可用原則屬性和限制類型的參考。 您也可參考常見使用案例的範例原則。

什麼是原則定義？

原則定義是 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 數值 值為 0 時表示沒有自動終止。 隱藏時，從 UI 移除自動終止核取方塊和值輸入。
azure_attributes.availability 字串 控制計算會使用隨選或現成執行個體 (ON_DEMAND_AZURE 或 SPOT_WITH_FALLBACK_AZURE)。
azure_attributes.first_on_demand 數值 控制要放在隨選執行個體上的節點數目。
azure_attributes.spot_bid_max_price 數值 控制 Azure 現成執行個體的最高價格。
cluster_log_conf.path 字串 記錄檔的目的地 URL。
cluster_log_conf.type 字串 記錄目的地的類型。 DBFS 是唯一可接受的值。
cluster_name 字串 叢集名稱。
custom_tags.* 字串 藉由附加標記名稱來控制特定標記值，例如：custom_tags.<mytag>。
data_security_mode 字串 設定叢集的存取模式。 Unity 目錄需要 SINGLE_USER 或 USER_ISOLATION (UI 中的共用存取模式)。 NONE 的值表示未啟用任何安全性功能。
docker_image.basic_auth.password 字串 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 字串 * 會參考屬性陣列中 init 指令碼的索引。 請參閱陣列屬性的寫入原則。
instance_pool_id 字串 如果也定義了 driver_instance_pool_id，則為控制背景工作角色節點所使用的集區，否則為控制所有叢集節點的集區。 如果您使用背景工作角色節點的集區，也必須使用驅動程式節點的集區。 隱藏時，從 UI 移除集區選擇。
driver_instance_pool_id 字串 如果指定，請為驅動程式節點設定不同於背景工作角色節點的集區。 如果未指定，則繼承 instance_pool_id。 如果您使用背景工作角色節點的集區，也必須使用驅動程式節點的集區。 隱藏時，從 UI 移除驅動程式集區選擇。
node_type_id 字串 隱藏時，從 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 字串 透過 API 指定的 Spark 映像版本名稱 (Databricks Runtime)。 您也可使用以動態方式選取 Databricks Runtime 的特殊原則值。 請參閱 Databricks Runtime 選擇的特殊原則值。
workload_type.clients.jobs boolean 定義計算資源是否可用於作業。 請參閱防止計算與作業搭配使用。
workload_type.clients.notebooks boolean 定義計算資源是否可與筆記本搭配使用。 請參閱防止計算與作業搭配使用。

虛擬屬性路徑

下表包含了原則支援的兩個額外綜合屬性：

屬性路徑 類型 描述
dbus_per_hour 數值 代表資源每小時可使用的最大 DBU 的匯出屬性，包括驅動程式節點。 此計量是控制個別計算層級成本的直接方式。 搭配範圍限制使用。
cluster_type 字串 表示可建立的叢集類型：

Azure Databricks 全用途計算的 - all-purpose
由作業排程器所建立的作業計算 - job
為差異即時資料表管線建立的計算 - dlt

允許或封鎖從原則建立的指定計算類型。 如果不允許 all-purpose 值，則不會在全用途建立計算 UI 中顯示該原則。 如果不允許 job 值，則不會在建立作業 UI 中顯示該原則。

Databricks Runtime 選擇的特殊原則值

spark_version 屬性支援根據目前支援的 Databricks Runtime 版本集合，動態對應至 Databricks Runtime 版本的特殊值。

spark_version 屬性中可以使用下列值：

  • auto:latest：對應至最新的 GA 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：對應至次新的 GA Databricks Runtime 版本。 例如，如果 auto:latest 是 14.2，則 auto:prev-major 為 13.3。
  • auto:prev-major-ml：對應至次新的 GA 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 Runtime 版本的計算，才能做出變更。

支援的原則類型

本節包含每個可用原則類型的參考。 原則類型有兩個類別：固定原則和限制原則。

固定原則可防止屬性上的使用者設定。 固定原則的兩種類型如下：

限制原則會限制使用者設定屬性的選項。 限制原則也能讓您設定預設值，並讓屬性成為選擇性。 請參閱其他限制原則欄位。

限制原則的選項如下：

固定原則

固定原則會將屬性限制為指定的值。 對於數值和布林值以外的屬性值，值必須以字串或轉換成字串來表示。

使用固定原則時，您也可將 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" ] }
}

Regex 原則

regex 原則會將可用的值限製為符合 regex 的值。 為了安全起因，請確定您的 regex 錨定在字串值的開頭與結尾。

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 指令碼，並且不允許其他版本的任何變體，您可使用下列模式：

{
  "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 提供的原則系列作為常見原則使用案例的範本。

一般計算原則

一般用途的計算原則旨在引導使用者並限制某些功能，同時需要標記、限制執行個體數目上限，以及強制執行逾時。

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

定義差異實時資料表管線計算的限制

注意

使用原則設定差異即時資料表計算時，Databricks 建議將單一原則套用至 default 和 maintenance 計算。

若要設定管線計算的原則，請建立原則，並將 cluster_type 欄位設定為 dlt。 下列範例會為差異即時資料表計算建立最小原則：

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