Computar a referência da política

Este artigo é uma referência para as definições de políticas do site compute. Os artigos incluem uma referência dos atributos de política e tipos de limitação disponíveis. Há também exemplos de políticas que o senhor pode consultar para casos de uso comuns.

O que são definições de políticas?

As definições de política são regras de política individuais expressas em JSON. Uma definição pode adicionar uma regra a qualquer um dos atributos controlados com a API de clusters. Por exemplo, essas definições definem um tempo de autoterminação de default, proíbem os usuários de usar o pool e impõem o uso de Photon:

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

Só pode haver uma limitação por atributo. O caminho de um atributo reflete o nome do atributo da API. Para atributos aninhados, o caminho concatena os nomes de atributos aninhados usando pontos. Os atributos que não estão definidos em uma definição de política não serão limitados.

Atributos suportados

As políticas são compatíveis com todos os atributos controlados com a API de clusters. O tipo de restrições que o senhor pode impor aos atributos pode variar de acordo com a configuração, com base no tipo e na relação com os elementos da interface do usuário. O senhor não pode usar políticas para definir as permissões do site compute.

O senhor também pode usar políticas para definir o máximo de DBUs por hora e o tipo de cluster. Consulte Caminhos de atributos virtuais.

A tabela a seguir lista os caminhos de atributos de política compatíveis:

Caminho do atributo	Tipo	Descrição
`autoscale.max_workers`	número opcional	Quando oculto, remove o campo de número máximo worker da interface do usuário.
`autoscale.min_workers`	número opcional	Quando oculto, remove o campo de número mínimo worker da interface do usuário.
`autotermination_minutes`	Número	Um valor de 0 representa que não há terminação automática. Quando oculto, remove a caixa de seleção de terminação automática e a entrada de valor da interface do usuário.
`cluster_log_conf.type`	string	O tipo de destino log. `DBFS` é o único valor aceitável.
`cluster_name`	string	O nome do cluster.
`custom_tags.*`	string	Controla valores de tag específicos anexando o nome da tag, por exemplo: `custom_tags.<mytag>`.
`data_security_mode`	string	Define o modo de acesso do cluster. O Unity Catalog requer `SINGLE_USER` ou `USER_ISOLATION` (modo de acesso compartilhado na interface do usuário). Um valor de `NONE` significa que nenhum recurso de segurança está ativado.
`driver_node_type_id`	strings opcionais	Quando oculto, remove a seleção do tipo de nó do driver da interface do usuário.
`init_scripts..workspace.destination` `init_scripts..volumes.destination` `init_scripts..gcs.destination` `init_scripts..file.destination`	string	`*` refere-se ao índice do init script na matriz de atributos. Consulte Escrever políticas para atributos de matriz.
`instance_pool_id`	string	Controla o pool usado pelos nós worker se `driver_instance_pool_id` também estiver definido ou, caso contrário, para todos os nós cluster. Se o senhor usar o pool para os nós do worker, também deverá usar o pool para o nó do driver. Quando oculto, remove a seleção de pool da interface do usuário.
`driver_instance_pool_id`	string	Se especificado, configura um pool diferente para o nó do driver e para os nós do worker. Se não for especificado, herda `instance_pool_id`. Se o senhor usar o pool para os nós do worker, também deverá usar o pool para o nó do driver. Quando oculto, remove a seleção do pool de drivers da interface do usuário.
`gcp_attributes.availability`	string	Controla a disponibilidade do GCP (PREEMPTIBLE_GCP, PREEMPTIBLE_WITH_FALLBACK_GCP ou ON_DEMAND_GCP).
`gcp_attributes.google_service_account`	string	Controla o serviço GCP account anexado ao cluster.
`gcp_attributes.local_ssd_count`	Número	Controla o número de SSD locais anexados a cada nó do cluster.
`gcp_attributes.availability`	boolean	Defina como `true` para permitir que o trabalhador seja iniciado usando instâncias de VM preemptivas.
`gcp_attributes.zone_id`	string	Controla a ID da zona GCP.
`node_type_id`	string	Quando oculto, remove a seleção do tipo de nó worker da interface do usuário.
`num_workers`	número opcional	Quando oculto, remove a especificação do número worker da interface do usuário.
`runtime_engine`	string	Determina se o cluster usa o Photon ou não. Os valores possíveis são `PHOTON` ou `STANDARD`.
`single_user_name`	string	O nome de usuário para acesso de usuário único por passagem de credenciais.
`spark_conf.*`	strings opcionais	Controle valores de configuração específicos anexando o nome da configuração key. Por exemplo, `spark_conf.spark.executor.memory`.
`spark_env_vars.*`	strings opcionais	Controle os valores específicos da variável de ambiente Spark anexando a variável de ambiente, por exemplo: `spark_env_vars.<environment variable name>`.
`spark_version`	string	O nome da versão da imagem do Spark, conforme especificado pela API (o Databricks Runtime). O senhor também pode usar valores de política especiais que selecionam dinamicamente o Databricks Runtime. Consulte Valores especiais de política para a seleção do Databricks Runtime.
`workload_type.clients.jobs`	boolean	Define se o recurso compute pode ser usado para o trabalho. Consulte Impedir que o site compute seja usado com o Job.
`workload_type.clients.notebooks`	boolean	Define se o recurso compute pode ser usado com o Notebook. Consulte Impedir que o site compute seja usado com o Job.

Caminhos de atributos virtuais

Essa tabela inclui dois atributos sintéticos adicionais compatíveis com as políticas:

Caminho do atributo

Tipo

Descrição

dbus_per_hour

Número

Atributo calculado que representa o máximo de DBUs que um recurso pode usar por hora, incluindo o nó do driver. Essa métrica é uma forma direta de controlar o custo no nível individual compute. Use com limitação de alcance.

cluster_type

string

Representa o tipo de cluster que pode ser criado:

all-purpose para Databricks all-purpose compute
job para Job compute criado pelo programador Job
dlt para compute criado para Delta Live Tables pipeline

Permitir ou bloquear tipos especificados de compute a serem criados a partir da política. Se o valor all-purpose não for permitido, a política não será mostrada na interface de usuário multifuncional create compute. Se o valor job não for permitido, a política não será exibida na interface de usuário create Job compute .

Valores de política especiais para a seleção do Databricks Runtime

O atributo spark_version suporta valores especiais que mapeiam dinamicamente para uma versão do Databricks Runtime com base no conjunto atual de versões suportadas do Databricks Runtime.

Os valores a seguir podem ser usados no atributo spark_version:

auto:latest: Mapeia para a versão mais recente do GA Databricks Runtime.
auto:latest-ml: Mapeia para a versão mais recente do Databricks Runtime ML.
auto:latest-lts: Mapeia para a versão mais recente de suporte de longo prazo (LTS) do Databricks Runtime.
auto:latest-lts-ml: Mapeia para a versão mais recente do LTS Databricks Runtime ML.
auto:prev-major: Mapeia para a segunda versão mais recente do GA Databricks Runtime. Por exemplo, se auto:latest for 14,2, então auto:prev-major será 13,3.
auto:prev-major-ml: Mapeia para a segunda versão mais recente do GA Databricks Runtime ML. Por exemplo, se auto:latest for 14,2, então auto:prev-major será 13,3.
auto:prev-lts: Mapeia para a segunda versão mais recente do LTS Databricks Runtime. Por exemplo, se auto:latest-lts for 13,3, então auto:prev-lts será 12,2.
auto:prev-lts-ml: Mapeia para a segunda versão mais recente do LTS Databricks Runtime ML. Por exemplo, se auto:latest-lts for 13,3, então auto:prev-lts será 12,2.

Observação

O uso desses valores não faz com que o site compute seja atualizado automaticamente quando uma nova versão de tempo de execução é lançada. Um usuário deve editar explicitamente o compute para que a versão Databricks Runtime seja alterada.

Tipos de políticas compatíveis

Esta seção inclui uma referência para cada um dos tipos de política disponíveis. Há duas categorias de tipos de política: políticas fixas e políticas de limitação.

As políticas corrigidas impedem a configuração do usuário em um atributo. Os dois tipos de apólices fixas são:

Política fixa
Política proibida

As políticas de limitação limitam as opções de um usuário para configurar um atributo. As políticas de limitação também permitem que o senhor defina valores default e torne os atributos opcionais. Consulte Campos adicionais de política de limitação.

Suas opções para limitar as políticas são:

Política de lista de permissões
Política de lista de bloqueio
Política Regex
Política de intervalo
Política ilimitada

Política fixa

As políticas fixas limitam o atributo ao valor especificado. Para valores de atributos que não sejam numéricos e Boolean, o valor deve ser representado por ou conversível em uma cadeia de caracteres.

Com políticas fixas, o senhor também pode ocultar o atributo da interface do usuário definindo o campo hidden como true.

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

Esse exemplo de política corrige a versão do Databricks Runtime e oculta o campo da UI do usuário:

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

Política proibida

Uma política proibida impede que os usuários configurem um atributo. As políticas proibidas são compatíveis apenas com atributos opcionais.

interface ForbiddenPolicy {
    type: "forbidden";
}

Essa política proíbe anexar um pool ao compute.

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

Política da lista de permissões

Uma política de lista de permissão especifica uma lista de valores que o usuário pode escolher ao configurar um atributo.

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

Esse exemplo de lista de permissão permite que o usuário selecione entre duas versões do Databricks Runtime:

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

Política de lista de bloqueio

A política de lista de bloqueio lista os valores não permitidos. Como os valores devem ser correspondências exatas, essa política pode não funcionar conforme o esperado quando o atributo é flexível na forma como o valor é representado (por exemplo, permitindo espaços à esquerda e à direita).

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

Este exemplo impede que o usuário selecione 7.3.x-scala2.12 como Databricks Runtime.

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

Política Regex

Uma política de regex limita os valores disponíveis àqueles que correspondem à regex. Por segurança, certifique-se de que seu regex esteja ancorado no início e no fim do valor das cadeias de caracteres.

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

Este exemplo limita as versões do Databricks Runtime que um usuário pode selecionar:

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

Política de alcance

Uma política de intervalo limita o valor a um intervalo especificado usando os campos minValue e maxValue. O valor deve ser um número decimal. Os limites numéricos devem ser representáveis como um valor de ponto flutuante duplo. Para indicar a falta de um limite específico, o senhor pode omitir minValue ou maxValue.

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

Este exemplo limita a quantidade máxima de trabalhadores a 10:

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

Política ilimitada

A política ilimitada é usada para tornar os atributos obrigatórios ou para definir o valor default na interface do usuário.

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

Este exemplo adiciona o COST_BUCKET tag ao compute:

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

Para definir um valor default para uma variável de configuração Spark, mas também permitir sua omissão (remoção):

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

Campos adicionais de política de limitação

Para limitar os tipos de política, o senhor pode especificar dois campos adicionais:

defaultValue - O valor que é preenchido automaticamente na UI de criação do compute.
isOptional - Uma política de limitação em um atributo o torna automaticamente obrigatório. Para tornar o atributo opcional, defina o campo isOptional como true.

Observação

default não são aplicados automaticamente a compute criado com o clusters API. Para aplicar os valores do default usando o API, adicione o parâmetro apply_policy_default_values à definição do compute e defina-o como true.

Este exemplo de política especifica o valor default id1 para pool, mas o torna opcional. Ao criar o compute, o senhor pode selecionar um pool diferente ou optar por não usar um.

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

Escrevendo políticas para atributos de matriz

O senhor pode especificar políticas para atributos de matriz de duas maneiras:

Limitações genéricas para todos os elementos do array. Essas limitações usam o símbolo curinga * no caminho da política.
Limitações específicas para um elemento de matriz em um índice específico. Essas limitações usam um número no caminho.

Por exemplo, para o atributo de matriz init_scripts, os caminhos genéricos começam com init_scripts.* e os caminhos específicos com init_scripts.<n>, em que <n> é um índice inteiro na matriz (começando com 0). O senhor pode combinar limitações genéricas e específicas e, nesse caso, a limitação genérica se aplica a cada elemento do array que não tenha uma limitação específica. Em cada caso, apenas uma limitação da apólice será aplicada.

As seções a seguir mostram exemplos de exemplos comuns que usam atributos de matriz.

Exigir entradas específicas de inclusão

O senhor não pode exigir valores específicos sem especificar a ordem. Por exemplo:

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

Exigir um valor fixo de toda a lista

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

Proibir totalmente o uso

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

Permitir entradas que sigam uma restrição específica

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

Corrigir um conjunto específico de script de inicialização

No caso de caminhos init_scripts, a matriz pode conter uma ou várias estruturas para as quais todas as variantes possíveis podem precisar ser tratadas, dependendo do caso de uso. Por exemplo, para exigir um conjunto específico de script de inicialização e não permitir qualquer variante da outra versão, o senhor pode usar o seguinte padrão:

{
  "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.*.gcs.destination": {
    "type": "forbidden"
  },
  "init_scripts.*.file.destination": {
    "type": "forbidden"
  }
}

Exemplos de políticas

Esta seção inclui exemplos de políticas que o senhor pode usar como referência para criar suas próprias políticas. O senhor também pode usar as Databricks famílias de políticas fornecidas pelo site como padrão para casos de uso de políticas comuns.

Política geral do site compute
Definir limites para Delta Live Tables pipeline compute
Apólice simples de médio porte
Job-política exclusiva
Política de metastore externo
Impedir que o site compute seja usado com o Job
Remover a política de autoescala
Personalizado tag enforcement

Política geral de computação

Uma política de propósito geral compute destinada a orientar os usuários e restringir algumas funcionalidades, exigindo tags, restringindo o número máximo de instâncias e aplicando o tempo limite.

{
  "instance_pool_id": {
    "type": "forbidden",
    "hidden": true
  },
  "spark_version": {
    "type": "regex",
    "pattern": "12\\.[0-9]+\\.x-scala.*"
  },
  "node_type_id": {
    "type": "allowlist",
    "values": [
      "n2-highmem-4",
      "n2-highmem-8",
      "n2-highmem-16"
    ],
    "defaultValue": "n2-highmem-4"
  },
  "driver_node_type_id": {
    "type": "fixed",
    "value": "n2-highmem-8",
    "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"
  }
}

Definir limites para a computação do pipeline do Delta Live Tables

Observação

Ao usar políticas para configurar Delta Live Tables compute, Databricks recomenda aplicar uma única política a default e maintenance compute.

Para configurar uma política para pipeline compute, crie uma política com o campo cluster_type definido como dlt. O exemplo a seguir cria uma política mínima para um Delta Live Tables compute:

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

Apólice simples de médio porte

Permite que os usuários criem um compute de tamanho médio com configuração mínima. O único campo obrigatório no momento da criação é o nome compute; o restante é fixo e oculto.

{
  "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": "n2-highmem-4",
    "hidden": true
  },
  "driver_node_type_id": {
    "type": "fixed",
    "value": "i3.xlarge",
    "hidden": true
  },
  "spark_version": {
    "type": "fixed",
    "value": "auto:latest-ml",
    "hidden": true
  },
  "custom_tags.team": {
    "type": "fixed",
    "value": "product"
  }
}

Job-política exclusiva

Permite que os usuários criem Job compute para executar o trabalho. Os usuários não podem criar compute para todos os fins usando essa política.

{
  "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": "[na][1-2]d?-(?:standard|highmem)-[0-96]"
  },
  "driver_node_type_id": {
    "type": "regex",
    "pattern": "[na][1-2]d?-(?:standard|highmem)-[0-96]"
  },
  "spark_version": {
    "type": "unlimited",
    "defaultValue": "auto:latest-lts"
  },
  "custom_tags.team": {
    "type": "fixed",
    "value": "product"
  }
}

Política de metastore externo

Permite que os usuários criem o site compute com um metastore definido pelo administrador já anexado. Isso é útil para permitir que os usuários criem seus próprios compute sem exigir configuração adicional.

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

Impedir que o site compute seja usado com o Job

Essa política impede que os usuários usem o site compute para executar o trabalho. Os usuários só poderão usar o compute com o Notebook.

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

Remover a política de autoescala

Essa política desativa a autoescala e permite que o usuário defina o número de trabalhadores dentro de um determinado intervalo.

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

Aplicação de tags personalizadas

Para adicionar uma regra compute tag a uma política, use o atributo custom_tags.<tag-name>.

Por exemplo, qualquer usuário que use essa política precisa preencher um COST_CENTER tag com 9999, 9921 ou 9531 para que o compute seja iniciado:

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