Referência de política de computação

Este artigo é uma referência para definições de políticas 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 você pode consultar para casos de uso comuns.

Quais são as definições de política?

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 pela API Clusters. Por exemplo, essas definições definem um tempo de encerramento automático default , proíbem os usuários de usar 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 dos atributos aninhados usando pontos. Os atributos que não estão definidos numa definição de política não serão limitados.

Atributos suportados

As políticas oferecem suporte a todos os atributos controlados pela API Clusters. O tipo de restrições que você pode colocar nos 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. Você não pode usar políticas para definir permissões compute .

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

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

Caminho do atributo

Tipo

Descrição

autoscale.max_workers

número opcional

Quando oculto, remove o campo de número máximo worker da UI.

autoscale.min_workers

número opcional

Quando oculto, remove o campo de número mínimo worker da UI.

autotermination_minutes

número

Um valor 0 representa nenhum encerramento automático. Quando oculto, remove a caixa de seleção de encerramento automático e a entrada de valor da IU.

cluster_log_conf.type

string

O tipo de destino dos registros. DBFS é o único valor aceitável.

cluster_name

string

O nome dos clusters .

custom_tags.*

string

Controla valores tags específicas anexando o nome tags , por exemplo: custom_tags.<mytag>.

data_security_mode

string

Define o modo de acesso dos clusters. O Unity Catalog requer SINGLE_USER ou USER_ISOLATION (modo de acesso compartilhado na IU). Um valor NONE significa que nenhum recurso de segurança está ativado.

driver_node_type_id

stringsopcionais

Quando oculto, remove a seleção do tipo de nó do driver da UI.

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 Escrevendo políticas para atributos de array.

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 clusters . Se você usar pool para nós worker , também deverá usar pool para o nó do driver. Quando oculto, remove a seleção do pool da IU.

driver_instance_pool_id

string

Se especificado, configura um pool diferente para o nó do driver e para os nós worker . Se não for especificado, herdará instance_pool_id. Se você usar pool para nós worker , também deverá usar 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 a account de serviço do GCP anexada aos clusters.

gcp_attributes.local_ssd_count

número

Controla o número de SSD locais anexados a cada nó dos clusters.

gcp_attributes.availability

boolean

Defina como true para permitir que worker seja iniciado usando instâncias de VM preemptivas.

gcp_attributes.zone_id

string

Controla o ID da zona do GCP.

node_type_id

string

Quando oculto, remove a seleção do tipo de nó worker da UI.

num_workers

número opcional

Quando oculto, remove a especificação do número worker da UI.

runtime_engine

string

Determina se os clusters usam 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 de passagem de credencial.

spark_conf.*

stringsopcionais

Controle valores de configuração específicos anexando o nome key de configuração. Por exemplo, spark_conf.spark.executor.memory.

spark_env_vars.*

stringsopcionais

Controle valores específicos de variáveis de ambiente do 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 Job. Consulte Impedir que compute seja usada com Job.

workload_type.clients.notebooks

boolean

Define se o recurso compute pode ser usado com Notebook. Consulte Impedir que compute seja usada com Job.

Caminhos de atributos virtuais

Esta tabela inclui dois atributos sintéticos adicionais suportados por 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. Essas métricas são uma forma direta de controlar custos no nível compute individual. Use com limitação de alcance.

cluster_type

string

Representa o tipo de clusters que podem ser criados:

  • all-purpose para computemultifuncional do Databricks

  • job para Job compute criado pelo Job programador

  • dlt para compute criada para pipelineDelta Live Tables

Permitir ou bloquear tipos específicos 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 IU de criação compute para todos os fins. Se o valor job não for permitido, a política não será mostrada na UI de criação 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 seguintes valores 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 site compute para que a versão do 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. Existem duas categorias de tipos de políticas: políticas fixas e políticas limitantes.

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

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 definir valores default e tornar os atributos opcionais. Consulte Campos adicionais de política de limitação.

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

Política fixa

As políticas fixas limitam o atributo ao valor especificado. Para valores de atributos diferentes de numéricos e Boolean, o valor deve ser representado ou conversível em strings.

Com políticas fixas, você também pode ocultar o atributo da IU definindo o campo hidden como true.

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

Esta política de exemplo corrige a versão do Databricks Runtime e oculta o campo da UI do utilizador:

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

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

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

Política de lista de permissões

Uma política de lista de permissões 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;
}

Este exemplo de lista de permissões 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 valores não permitidos. Como os valores devem ser correspondências exatas, esta política pode não funcionar conforme o esperado quando o atributo é tolerante 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 o 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 ao regex. Por segurança, certifique-se de que sua regex esteja ancorada no início e no final do valor da strings .

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, você 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 worker 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 UI.

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

Este exemplo adiciona as tags COST_BUCKET ao compute:

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

Para definir um valor default para uma variável de configuração do Spark, mas também permitir omiti-la (removê-la):

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

Campos de política de limitação adicionais

Para limitar os tipos de política, você pode especificar dois campos adicionais:

  • defaultValue - O valor que é preenchido automaticamente na interface de criação compute .

  • isOptional - Uma política de limitação de um atributo torna-o automaticamente obrigatório. Para tornar o atributo opcional, defina o campo isOptional como true.

Observação

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

Este exemplo de política especifica o valor default id1 para o pool, mas o torna opcional. Ao criar o compute, você 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 array

Você 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 array 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>, onde <n> é um índice inteiro na matriz (começando com 0). Você pode combinar limitações genéricas e específicas; nesse caso, a limitação genérica se aplica a cada elemento da matriz que não possui uma limitação específica. Em cada caso, apenas uma limitação da política será aplicada.

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

Exigir entradas específicas de inclusão

Você 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 restrições específicas

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

Corrija um conjunto específico de init script

No caso de caminhos init_scripts , a matriz pode conter uma das múltiplas 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 init script e proibir qualquer variante da outra versão, você 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 você pode usar como referência para criar suas próprias políticas. Você também pode usar as famílias de políticas fornecidas pelo Databricks como padrão para casos de uso de políticas comuns.

Política geral de computação

Uma política compute de uso geral destinada a orientar os usuários e restringir algumas funcionalidades, ao mesmo tempo que exige tags, restringe o número máximo de instâncias e impõe 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 na computação do pipeline Delta Live Tables

Observação

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

Para configurar uma política para um compute de pipeline, crie uma política com o campo cluster_type definido como dlt. O exemplo a seguir cria uma política mínima para um compute do 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
  }
}

Política simples de médio porte

Permite que os usuários criem uma compute de tamanho médio com configuração mínima. O único campo obrigatório no momento da criação é o nome compute ; o resto é 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"
  }
}

Política somenteJob

Permite que os usuários criem Job compute para execução Job. Os usuários não podem criar compute para todos os fins usando esta 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 compute com um metastore definido pelo administrador já anexado. Isto é útil para permitir que os usuários criem sua própria 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 a computação seja usada com Job

Esta política impede que os usuários usem o compute para execução Job. Os usuários só poderão usar a compute com Notebook.

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

Remover política autoscale

Esta política desativa autoscale e permite ao utilizador definir o número de worker dentro de um determinado intervalo.

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

Aplicação de tags personalizadas

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

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

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