コンピューティング ポリシーのリファレンス

この記事は、コンピューティング ポリシー定義に関するリファレンスです。 使用可能なポリシー属性と制限タイプのリファレンスが含まれています。 また、一般的なユースケースの参考となるサンプル ポリシーもあります。

ポリシー定義とは

ポリシー定義は、JSON 形式で表現される個々のポリシー ルールです。 1 つの定義で、Clusters API で制御される任意の属性にルールを 1 つ追加できます。 たとえば、次に示す例は、既定の自動終了時間の設定、ユーザーによるプール使用の禁止、Photon 使用の義務付けを適用する定義です。

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

属性あたりの制限数は 1 つのみです。 属性のパスは、API の属性名に対応しています。 ネストされた属性を指定するには、ネストされた属性名をドット区切りで連結したパスを使用します。 ポリシー定義内に定義されていない属性については、制限が適用されません。

サポートされている属性

ポリシーでは、クラスター API で制御されるすべての属性をサポートされています。 属性に設定できる制限の種類は、属性の種類によって、また、属性と UI 要素との関係に基づいて、設定ごとに異なる場合があります。 ポリシーを使用してコンピューティングのアクセス許可を定義することはできません。

ポリシーでは、1 時間あたりの最大 DBU やクラスターの種類を設定することもできます。 「仮想属性パス」を参照してください。

次の表に、サポートされているポリシー属性パスの一覧を示します。

属性パス Type 説明
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_price_percent 数値 Azure スポット インスタンスの最大価格を制御します。
cluster_log_conf.path string ログファイルの送信先 URL。
cluster_log_conf.type string ログの格納先の種類。 許される値は DBFS のみです。
cluster_name string クラスター名。
custom_tags.* string タグ名を追加して、特定のタグ値を制御します (例: custom_tags.<mytag>)。
data_security_mode string クラスターのアクセス モードを設定します。 Unity Catalog には、SINGLE_USER または USER_ISOLATION (UI の共有アクセス モード) が必要です。 値 NONE は、セキュリティ機能が有効になっていないことを意味します。
docker_image.basic_auth.password string Databricks Container Services イメージ基本認証のパスワード。
docker_image.basic_auth.username string Databricks Container Services イメージ基本認証のユーザー名。
docker_image.url string Databricks Container Services イメージの URL を制御します。 非表示の場合、UI から Databricks Container Services セクションを削除します。
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 * は、属性配列内の init スクリプトのインデックスを参照します。 「配列属性用ポリシーの記述方法」を参照してください。
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 string クラスターで Photon を使用するかどうかを指定します。 指定できる値は PHOTON または STANDARD です。
single_user_name string 資格情報パススルー シングル ユーザー アクセスのユーザー名。
spark_conf.* 省略可能な文字列 構成キー名を追加して、特定の構成値を制御します (例: spark_conf.spark.executor.memory)。
spark_env_vars.* 省略可能な文字列 環境変数を追加して、特定の Spark 環境変数の値を制御します (例: spark_env_vars.<environment variable name>)。
spark_version string API (Databricks Runtime) で指定された Spark イメージのバージョン名。 Databricks Runtime を動的に選ぶ特別なポリシー値を使うこともできます。 「Databricks Runtime の選択に関する特別なポリシー値」をご覧ください。
workload_type.clients.jobs boolean コンピューティング リソースをジョブに使用できるかどうかを定義します。 「ジョブでコンピューティングが使用されないようにする」を参照してください。
workload_type.clients.notebooks boolean コンピューティング リソースをノートブックで使用できるかどうかを定義します。 「ジョブでコンピューティングが使用されないようにする」を参照してください。

仮想属性パス

次の表に、ポリシーで上記以外にサポートされている 2 つの合成属性を示します。

属性パス Type Description
dbus_per_hour 数値 1 つのリソースが 1 時間あたりに使用できる最大 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: 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 の最新の 1 つ前のバージョンにマップします。 たとえば、auto:latest が 14.2 の場合、auto:prev-major は 13.3 です。
  • auto:prev-major-ml: GA Databricks Runtime ML の最新の 1 つ前のバージョンにマップします。 たとえば、auto:latest が 14.2 の場合、auto:prev-major は 13.3 です。
  • auto:prev-lts: LTS Databricks Runtime の最新の 1 つ前のバージョンにマップします。 たとえば、auto:latest-lts が 13.3 の場合、auto:prev-lts は 12.2 です。
  • auto:prev-lts-ml: LTS Databricks Runtime ML の最新の 1 つ前のバージョンにマップします。 たとえば、auto:latest-lts が 13.3 の場合、auto:prev-lts は 12.2 です。

Note

これらの値を使っても、新しいランタイム バージョンがリリースされたときに、コンピューティングが自動更新されることはありません。 ユーザーは、変更する Databricks Runtime バージョンのコンピューティングを明示的に編集する必要があります。

サポートされているポリシーの種類

このセクションでは、使用可能なポリシーの種類別のリファレンスを示します。 ポリシーの種類には、固定ポリシーと制限ポリシーの 2 つのカテゴリがあります。

固定ポリシーは、特定の属性についてユーザーによる構成を禁止するポリシーです。 固定ポリシーには以下の 2 種類があります。

制限ポリシーは、特定の属性についてユーザーによる構成の選択肢を制限するポリシーです。 また、既定値を設定して、その属性をオプション属性にすることもできます。 「その他の制限ポリシー フィールド」を参照してください。

制限ポリシーには以下のオプションがあります。

固定ポリシー

固定ポリシーは、属性値を特定の値に限定するポリシーです。 数値型とブール値型を除く属性値は、文字列形式で表現される、または文字列形式に変換できる必要があります。

固定ポリシーでは、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;
}

次の例では、指定した 2 つの 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;
}

次の例では、Databricks Runtime のバージョン 7.3.x-scala2.12 を選択することを禁止しています。

{
  "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 フィールドで限定するポリシーです。 値は 10 進数である必要があります。 数値の制限は、倍精度浮動小数点値として表現可能でなければなりません。 上限または下限の一方のみを指定する場合は、minValuemaxValue のどちらかを省略できます。

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

その他の制限ポリシー フィールド

各種の制限ポリシーには、以下に示す 2 つの追加フィールドを指定できます。

  • defaultValue - コンピューティング作成 UI に自動的に入力される値。
  • isOptional - 制限ポリシーを使用すると、その属性は自動的に必須となります。 省略可能にするには、isOptional フィールドを true に設定します。

Note

Clusters API でコンピューティングを作成する場合、自動的に既定値が適用されることはありません。 API を使用して既定値を適用するには、コンピューティング定義に apply_policy_default_values パラメーターを追加し、true に設定します。

このポリシー例では、ワーカー ノードのプールの既定値 id1 を指定しますが、これは省略可能です。 コンピューティングの作成時には、別のプールを選択することや、プールを使用しないようにすることもできます。 driver_instance_pool_id をポリシー内に定義しない、またはコンピューティング作成時に定義しない場合、ワーカー ノードとドライバー ノードに同じプールが使用されます。

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

配列属性用ポリシーの記述方法

配列属性のポリシーは、次の 2 つの方法で指定できます。

  • すべての配列要素に関する一般的な制限。 これらの制限では、ポリシー パス * ワイルドカード記号が使用されます。
  • 特定のインデックスでの配列要素に関する特定の制限。 これらの制限では、パスに数値が使用されます。

たとえば、配列属性 init_scripts の場合、一般的なパスは init_scripts.* で始まり、特定のパスは init_scripts.<n> で始まります。ここで、<n> は配列内の整数インデックスです (0 から始まる)。 一般的な制限と特定の制限を組み合わせることができます。その場合、一般的な制限は、特定の制限を持たない各配列要素に適用されます。 ケースごとに適用されるポリシーの制限は 1 つのみです。

以降のセクションでは、配列属性を使用する一般的な例を示します。

特定のエントリを含めることを必須にする

順序を指定せずに特定の値を要求することはできません。 次に例を示します。

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

Delta Live Tables パイプライン コンピューティングの制限を定義する

Note

ポリシーを使用して 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> 属性を使います。

たとえば、このポリシーを使うすべてのユーザーは、コンピューティングを起動するために、COST_CENTER タグに 9999、9921、または 9531 を入力する必要があります。

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