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

Este artigo é uma referência para definições de política de computação. Os artigos incluem uma referência dos atributos de política disponíveis e tipos de limitação. Há também exemplos de políticas que você pode referenciar 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 encerramento automático padrão, proíbem os usuários de usar pools 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 suportam todos os atributos controlados com a API de Clusters. O tipo de restrições que você pode colocar em atributos pode variar por configuração com base em seu tipo e relação com os elementos da interface do usuário. Não é possível usar políticas para definir permissões de computação.

Você 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 atributo de política suportados:

Caminho do atributo	Tipo	Description
autoscale.max_workers	número opcional	Quando oculto, remove o campo número máximo de trabalhadores da interface do usuário.
autoscale.min_workers	número opcional	Quando oculto, remove o campo número mínimo de trabalhadores da interface do usuário.
autotermination_minutes	Número	Um valor de 0 não representa nenhuma 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.
azure_attributes.availability	string	Controla o uso de computação sob demanda ou instâncias spot (ON_DEMAND_AZURE ou SPOT_WITH_FALLBACK_AZURE).
azure_attributes.first_on_demand	Número	Controla o número de nós a serem colocados em instâncias sob demanda.
azure_attributes.spot_bid_max_price	Número	Controla o preço máximo para instâncias spot do Azure.
cluster_log_conf.path	string	A URL de destino dos arquivos de log.
cluster_log_conf.type	string	O tipo de destino do log. DBFS é o único valor aceitável.
cluster_name	string	O nome do cluster.
custom_tags.*	string	Controle 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 significa que nenhum recurso de NONE segurança está habilitado.
docker_image.basic_auth.password	string	A senha para a autenticação básica da imagem do Databricks Container Services.
docker_image.basic_auth.username	string	O nome de usuário para a autenticação básica da imagem do Databricks Container Services.
docker_image.url	string	Controla a URL da imagem do Databricks Container Services. Quando oculto, remove a seção Databricks Container Services da interface do usuário.
driver_node_type_id	string opcional	Quando oculto, remove a seleção de tipo de nó do driver da interface do usuário.
enable_local_disk_encryption	boolean	Defina como true para habilitar ou false desabilitar discos de criptografia conectados localmente ao cluster (conforme especificado por meio da API).
init_scripts.*.workspace.destination init_scripts.*.volumes.destination init_scripts.*.abfss.destination init_scripts.*.file.destination	string	* refere-se ao índice do script init na matriz de atributos. Consulte Escrevendo políticas para atributos de matriz.
instance_pool_id	string	Controla o pool usado pelos nós de trabalho, se driver_instance_pool_id também estiver definido, ou para todos os nós de cluster de outra forma. Se você usar pools para nós de trabalho, também deverá usar pools para o nó de 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 do que para os nós de trabalho. Se não for especificado, herda .instance_pool_id Se você usar pools para nós de trabalho, também deverá usar pools para o nó de driver. Quando oculto, remove a seleção do pool de drivers da interface do usuário.
node_type_id	string	Quando oculto, remove a seleção de tipo de nó de trabalho da interface do usuário.
num_workers	número opcional	Quando oculto, remove a especificação do número de trabalhador da interface do usuário.
runtime_engine	string	Determina se o cluster usa Photon ou não. Os valores possíveis são PHOTON ou STANDARD.
single_user_name	string	O nome de usuário para credencial passa pelo acesso de usuário único.
spark_conf.*	string opcional	Controla valores de configuração específicos anexando o nome da chave de configuração, por exemplo: spark_conf.spark.executor.memory.
spark_env_vars.*	string opcional	Controla 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 por meio da API (Databricks Runtime). Você também pode usar valores de política especiais que selecionam dinamicamente o Databricks Runtime. Consulte Valores de política especiais para a seleção do Databricks Runtime.
workload_type.clients.jobs	boolean	Define se o recurso de computação pode ser usado para trabalhos. Consulte Impedir que a computação seja usada com trabalhos.
workload_type.clients.notebooks	boolean	Define se o recurso de computação pode ser usado com blocos de anotações. Consulte Impedir que a computação seja usada com trabalhos.

Caminhos de atributos virtuais

Esta tabela inclui dois atributos sintéticos adicionais suportados por políticas:

Caminho do atributo	Tipo	Description
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 maneira direta de controlar o custo no nível de computação individual. Use com limitação de alcance.
cluster_type	string	Representa o tipo de cluster que pode ser criado: - all-purpose para computação multiuso do Azure Databricks - job para computação de trabalho criada pelo agendador de tarefas - dlt para computação criada para pipelines Delta Live Tables Permitir ou bloquear tipos especificados de computação a serem criados a partir da política. Se o all-purpose valor não for permitido, a política não será mostrada na interface do usuário de computação de criação para todos os fins. Se o job valor não for permitido, a política não será mostrada na interface do usuário de computação de trabalho de criação.

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

O spark_version atributo 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 spark_version atributo:

• 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 do Databricks Runtime de suporte de longo prazo (LTS).
• 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 é 14.2, então auto:prev-major é 13.3.
• auto:prev-major-ml: Mapeia para a segunda versão mais recente do GA Databricks Runtime ML. Por exemplo, se auto:latest é 14.2, então auto:prev-major é 13.3.
• auto:prev-lts: Mapeia para a segunda versão mais recente do LTS Databricks Runtime. Por exemplo, se auto:latest-lts é 13.3, então auto:prev-lts é 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 é 13.3, então auto:prev-lts é 12.2.

Nota

O uso desses valores não torna a atualização automática de computação quando uma nova versão de tempo de execução é lançada. Um usuário deve editar explicitamente a computação para que a versão do Databricks Runtime seja alterada.

Tipos de política suportados

Esta secçã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 limitativas.

Políticas fixas 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 limitantes limitam as opções de um usuário para configurar um atributo. As políticas de limitação também permitem definir valores padrão e tornar os atributos opcionais. Consulte Campos de política de limitação adicionais.

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

• Política de lista de permissões
• Política de lista de bloqueio
• Política Regex
• Política de alcance
• Política ilimitada

Política fixa

As políticas fixas limitam o atributo ao valor especificado. Para valores de atributo diferentes de numéricos e booleanos, o valor deve ser representado por ou conversível em uma cadeia de caracteres.

Com políticas fixas, você também pode ocultar o atributo da interface do usuário definindo o hidden campo 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 interface do usuário 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ó são compatíveis com atributos opcionais.

interface ForbiddenPolicy {
    type: "forbidden";
}

Esta política proíbe anexar pools à computação para nós de trabalho. Os pools também são proibidos para o nó do driver, porque driver_instance_pool_id herda a política.

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

Política de lista de permissões

Uma política allowlist especifica uma lista de valores entre os quais 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 allowlist 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, essa política pode não funcionar como esperado quando o atributo é brando 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 ao regex. Por segurança, certifique-se de que seu regex esteja ancorado no início e no final do valor da cadeia 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 minValue campos 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 um 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 necessários ou para definir o valor padrão na interface do usuário.

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

Este exemplo adiciona a COST_BUCKET tag ao cálculo:

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

Para definir um valor padrão 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 do usuário de computação de criação.
• isOptional - Uma política de limitação de um atributo torna-o automaticamente necessário. Para tornar o atributo opcional, defina o isOptional campo como true.

Nota

Os valores padrão não são aplicados automaticamente à computação criada com a API de Clusters. Para aplicar valores padrão usando a API, adicione o parâmetro apply_policy_default_values à definição de computação e defina-o como true.

Esta política de exemplo especifica o valor id1 padrão para o pool para nós de trabalho, mas o torna opcional. Ao criar a computação, você pode selecionar um pool diferente ou optar por não usar um. Se driver_instance_pool_id não estiver definido na política ou ao criar a computação, o mesmo pool será usado para nós de trabalho e o nó de driver.

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

Escrevendo políticas para atributos de matriz

Você pode especificar políticas para atributos de matriz de duas maneiras:

• Limitações genéricas para todos os elementos da matriz. 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 init_scriptsarray , 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, caso em que a limitação genérica se aplica a cada elemento de matriz que não tem uma limitação específica. Em cada caso, apenas uma limitação de política será aplicada.

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

Exigir entradas específicas de inclusão

Não é possível 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"
  }
}

Não permitir o uso completamente

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

Permitir entradas que seguem restrições específicas

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

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

No caso de caminhos, a matriz pode conter uma das várias estruturas para as quais todas as variantes possíveis podem precisar ser manipuladas, dependendo do caso de init_scripts uso. Por exemplo, para exigir um conjunto específico de scripts init e não permitir 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.*.abfss.destination": {
    "type": "forbidden"
  },
  "init_scripts.*.file.destination": {
    "type": "forbidden"
  }
}

Exemplos de política

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 Azure Databricks como modelos para casos de uso de políticas comuns.

• Política geral de computação
• Definir limites na computação do pipeline Delta Live Tables
• Política simples de média dimensão
• Política de criação de emprego
• Política de metastore externo
• Impedir que a computação seja usada com trabalhos
• Remover política de dimensionamento automático
• Aplicação de etiquetas personalizadas

Política geral de computação

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

Definir limites na computação do pipeline Delta Live Tables

Nota

Ao usar políticas para configurar a computação Delta Live Tables, o Databricks recomenda a aplicação de uma única política para o default e maintenance compute.

Para configurar uma política para uma computação de pipeline, crie uma política com o cluster_type campo definido como dlt. O exemplo a seguir cria uma política mínima para uma computação 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édia dimensão

Permite que os usuários criem uma computação de tamanho médio com configuração mínima. O único campo obrigatório no momento da criação é o nome do computador; o resto é fixo e escondido.

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

Política de criação de emprego

Permite que os usuários criem computação de trabalho para executar trabalhos. Os usuários não podem criar computação 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": "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"
  }
}

Política de metastore externo

Permite que os usuários criem computação com um metastore definido pelo administrador já conectado. Isso é útil para permitir que os usuários criem sua própria computação 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 trabalhos

Essa política impede que os usuários usem a computação para executar trabalhos. Os usuários só poderão usar a computação com notebooks.

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

Remover política de dimensionamento automático

Esta política desativa o dimensionamento automático 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 etiquetas personalizadas

Para adicionar uma regra de marca de computação a uma política, use o custom_tags.<tag-name> atributo.

Por exemplo, qualquer usuário que use essa política precisa preencher uma COST_CENTER tag com 9999, 9921 ou 9531 para que a computação seja iniciada:

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