Referência de 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. Existem também políticas de exemplo que você pode referenciar para casos de uso comuns.

O que são 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 um dos atributos controlados com a API de clusters. Por exemplo, essas definições definem um tempo de gerenciamento 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. Em atributos aninhados, o caminho concatena os nomes de atributo aninhados usando pontos. Atributos que não estão definidos em uma definição de política não serão limitados.

Atributos com suporte

As políticas dão suporte a todos os atributos controlados com a API de Clusters. O tipo de restrições que você pode colocar em atributos pode variar de acordo com a configuração baseada em seu tipo e relação com os elementos da interface do usuário. Você não pode 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 atributo virtual.

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

Caminho de atributo	Type	Descrição
autoscale.max_workers	número opcional	Quando oculto, remove o campo de número máximo de trabalhos da interface do usuário.
autoscale.min_workers	número opcional	Quando oculto, remove o campo de número mínimo de trabalhos da interface do usuário.
autotermination_minutes	número	Um valor igual a 0 representa nenhum encerramento automático. Quando oculto, remove a caixa de seleção de encerramento automático e a entrada de valor da interface do usuário.
azure_attributes.availability	string	Controla os usos da computação sob demanda ou as instâncias spot (ON_DEMAND_AZURE ou SPOT_WITH_FALLBACK_AZURE).
azure_attributes.first_on_demand	number	Controla o número de nós a serem colocados nas instâncias sob demanda.
azure_attributes.spot_bid_max_price	number	Controla o preço máximo das 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 de log. DBFS é o único valor aceitável.
cluster_name	string	O nome do cluster.
custom_tags.*	string	Controle os valores de marca específicos acrescentando o nome da marca, por exemplo: custom_tags.<mytag>.
data_security_mode	string	Define o modo de acesso do cluster. O Catálogo do Unity exige SINGLE_USER ou USER_ISOLATION (modo de acesso compartilhado na interface do usuário). Um valor igual a NONE significa que nenhum recurso de segurança está habilitado.
docker_image.basic_auth.password	string	A senha para a autenticação básica da imagem dos Serviços de Contêiner do Databricks.
docker_image.basic_auth.username	string	O nome de usuário para a autenticação básica da imagem dos Serviços de Contêiner do Databricks.
docker_image.url	string	Controla a URL da imagem dos Serviços de Contêiner do Databricks. Quando oculto, remove a seção Serviços de Contêiner do Databricks da interface do usuário.
driver_node_type_id	cadeia de caracteres opcional	Quando oculto, remove a seleção de tipo de nó de driver da interface do usuário.
enable_local_disk_encryption	booleano	Defina- o como true para habilitar ou como false ou desabilitar a criptografia de discos anexados 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 de inicialização na matriz de atributos. Consulte Políticas de gravação para atributos de matriz.
instance_pool_id	string	Controla o pool usado pelos nós de trabalho se driver_instance_pool_id também está definido, caso contrário, para todos os nós de cluster. Se você usar pools para nós de trabalho, também precisará usar pools para o nó do driver. Quando oculto, remove a seleção do pool da interface do usuário.
driver_instance_pool_id	string	Se especificado, configura um pool para o nó do driver diferente dos nós de trabalho. Se não especificado, herda instance_pool_id. Se você usar pools para nós de trabalho, também precisará usar pools para o nó do driver. Quando oculto, remove a seleção do pool de driver da interface do usuário.
node_type_id	string	Quando oculto, remove a seleção do tipo de nó de trabalho da interface do usuário.
num_workers	número opcional	Quando oculto, remove a especificação de número de trabalho 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 da passagem de credenciais.
spark_conf.*	cadeia de caracteres opcional	Controla valores de configuração específicos acrescentando o nome da chave de configuração, por exemplo: spark_conf.spark.executor.memory.
spark_env_vars.*	cadeia de caracteres opcional	Controla valores específicos de variáveis de ambiente do Spark acrescentando 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 (o 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 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 notebooks. Consulte Impedir que a computação seja usada com trabalhos.

Caminhos de atributo virtual

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

Caminho de atributo	Type	Descrição
dbus_per_hour	number	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 de computação individual. Uso com limitação de intervalo.
cluster_type	string	Representa o tipo de cluster que pode ser criado: - all-purpose para a Computação para Todas as Finalidades do Azure Databricks - job para computação de trabalho criada pelo agendador de trabalhos - dlt para computação criada para pipelines do Delta Live Tables Permita ou bloqueie tipos específicos de computação 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 do usuário do criação de computação para todas as finalidades. Se o valor job não for permitido, a política não será mostrada na interface do usuário de computação do trabalho de criação.

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

O atributo spark_version dá suporte a valores especiais que são mapeados dinamicamente para uma versão do Databricks Runtime, com base no conjunto atual de versões do Databricks Runtime com suporte.

Os valores a seguir podem ser usados no atributo spark_version:

• auto:latest: mapeia para a versão mais recente do GA do Databricks Runtime.
• auto:latest-ml: mapeia para a versão mais recente de ML do Databricks Runtime.
• 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 de ML do Databricks Runtime de LTS.
• auto:prev-major: mapeia para a segunda versão mais recente do GA do Databricks Runtime. Por exemplo, se auto:latest for 14.2, auto:prev-major será 13.3.
• auto:prev-major-ml: mapeia para a segunda versão mais recente de ML do Databricks Runtime. Por exemplo, se auto:latest for 14.2, auto:prev-major será 13.3.
• auto:prev-lts: mapeia para a segunda versão mais recente do Databricks Runtime de LTS. Por exemplo, se auto:latest-lts for 13.3, auto:prev-lts será 12.2.
• auto:prev-lts-ml: mapeia para a segunda versão mais recente de ML do Databricks Runtime de LTS. Por exemplo, se auto:latest-lts for 13.3, auto:prev-lts será 12.2.

Observação

Usar esses valores não faz com que a computação seja atualizada automaticamente quando uma nova versão de runtime é 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 com suporte

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

As políticas fixas impedem a configuração do usuário em um atributo. Estes são os dois tipos de políticas fixas:

• 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 você defina valores padrão e torne os atributos opcionais. Consulte Campos de política de limitação adicionais.

Estas são as opções de políticas de limitação:

• Política de lista de permitidos
• Política de lista de bloqueados
• Política de regex
• Política de intervalo
• Política ilimitada

Política fixa

As políticas fixas limitam o atributo ao valor especificado. Para valores de atributo diferentes de numérico e booliano, o valor precisa ser representado por ou convertido em uma cadeia de caracteres.

Com as políticas fixas, também é possível ocultar o atributo da interface do usuário 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 interface 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 somente com atributos opcionais.

interface ForbiddenPolicy {
    type: "forbidden";
}

Essa política proíbe a anexação de pools à computação para nós de trabalho. Os pools também são proibidos no nó de driver, pois driver_instance_pool_id herda a política.

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

Política de lista de permitidos

Uma política de lista de permitidos 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 permitidos 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 bloqueados

A política de lista de bloqueados lista valores não permitidos. Como os valores precisam ser correspondências exatas, essa política pode não funcionar conforme o esperado quando o atributo for flexível em relação a 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 de regex

Uma política de regex limita os valores disponíveis aos que correspondem ao regex. Por segurança, verifique se o regex está 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 intervalo

Uma política de intervalo limita o valor a um intervalo especificado usando os campos minValue e maxValue. O valor precisa ser um número decimal. Os limites numéricos precisam 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 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 marca COST_BUCKET à computação:

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

Para definir um valor padrão como uma variável de configuração do Spark, mas também permitir a omissão (remoção) dele:

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

Campos de política de limitação adicionais

Você pode especificar dois campos adicionais em uma política de limitação:

• defaultValue – O valor que é preenchido automaticamente na interface do usuário de criação de computação.
• isOptional – Uma política de limitação em um atributo o torna automaticamente necessário. Para tornar o atributo opcional, defina o campo isOptional como true.

Observação

Os valores padrão não são aplicados automaticamente na 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 padrão id1 para o pool de nós de trabalho, mas o torna opcional. Ao criar a computação, você pode selecionar outro pool ou optar por não usar um. Se driver_instance_pool_id não estiver definido na política ou quando a computação for criada, o mesmo pool será usado para nós de trabalho e para o nó de driver.

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

Políticas de gravação para atributos de matriz

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

• Limitações genéricas para todos os elementos de 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 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). 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 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 comuns que usam atributos de matriz.

Exigir entradas específicas da 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 absolutamente o uso

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

Permitir entradas que seguem restrição específica

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

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

No caso de caminhos init_scripts, a matriz pode conter uma das 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 scripts de inicialização e não permitir qualquer variante da outra versão, use 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íticas

Esta seção inclui exemplos de política que você pode usar como referências 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 comuns de uso de políticas.

• Política de computação geral
• Definir limites em computação de pipeline do Delta Live Tables
• Política simples de médio porte
• Política somente de trabalho
• Política de metastore externo
• Impedir que a computação seja usada com trabalhos
• Remover política de dimensionamento automático
• Imposição de marca personalizada

Política de computação geral

Uma política de computação de uso geral destina-se a orientar os usuários e restringir algumas funcionalidades, exigindo marcas, restringindo o número máximo de instâncias e impondo um 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 em computação de pipeline do Delta Live Tables

Observação

Ao usar políticas para configurar a computação do Delta Live Tables, o Databricks recomenda aplicar uma política única tanto para a computação default como para a maintenance.

Para configurar uma política para uma computação de pipeline, crie uma política com o campo cluster_type definido como dlt. O seguinte exemplo cria uma política mínima para uma computação 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 computação de médio porte com uma configuração mínima. O único campo obrigatório no momento da criação é o nome da computação. 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": "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 somente de trabalho

Permite que os usuários criem computação de trabalho para executar trabalhos. Os usuários não podem criar Computação para Todas as Finalidades 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": "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 uma computação com um metastore definido pelo administrador já anexado. Isso é útil para permitir que os usuários criem a própria computação sem a necessidade de 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 os usuários de usar 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

Essa política desabilita o dimensionamento automático e permite que o usuário defina o número de trabalhos dentro de um determinado intervalo.

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

Imposição de marca personalizada

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

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

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