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.

aws_attributes.availability

string

Controla a disponibilidade da AWS (SPOT, ON_DEMAND ou SPOT_WITH_FALLBACK)

aws_attributes.ebs_volume_count

Número

O número de volumes do AWS EBS.

aws_attributes.ebs_volume_size

Número

O tamanho (em GiB) dos volumes do AWS EBS.

aws_attributes.ebs_volume_type

string

O tipo de volumes do AWS EBS.

aws_attributes.first_on_demand

Número

Controla o número de nós a serem colocados em instâncias sob demanda.

aws_attributes.instance_profile_arn

string

Controla o site AWS instance profile.

aws_attributes.spot_bid_price_percent

Número

Controla o preço máximo para instâncias spot do AWS.

aws_attributes.zone_id

string

Controla a ID da zona do AWS.

cluster_log_conf.path

string

O URL de destino dos arquivos log.

cluster_log_conf.region

string

A região para o local S3.

cluster_log_conf.type

S3, DBFS ou NONE

O tipo de destino log.

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.

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 o 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

strings opcionais

Quando oculto, remove a seleção do tipo de nó do driver da interface do usuário.

enable_elastic_disk

boolean

Quando oculto, remove a caixa de seleção Enable autoscale local storage (Ativar armazenamento local de autoescala ) da interface do usuário.

enable_local_disk_encryption

boolean

Defina como true para ativar ou false para desativar a criptografia de discos conectados localmente ao cluster (conforme especificado pela API).

init_scripts.*.workspace.destination init_scripts.*.volumes.destination init_scripts.*.s3.destination init_scripts.*.file.destination init_scripts.*.s3.region

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.

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.

ssh_public_keys.*

string

* refere-se ao índice do key público na matriz de atributos. Consulte Escrever políticas para atributos de matriz.

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:

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 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 o pool ao site compute para nós worker. também são proibidos para o nó driver, pois driver_instance_pool_id herda a política.

{
  "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 os nós pool e worker, mas o torna opcional. Ao criar o compute, o senhor pode selecionar um pool diferente ou optar por não usar um. Se driver_instance_pool_id não for definido na política ou ao criar o compute, o mesmo pool será usado para os nós worker e o nó do driver.

{
  "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.*.s3.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 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": "unlimited",
    "defaultValue": "auto:latest-ml"
  },
  "node_type_id": {
    "type": "allowlist",
    "values": [
      "i3.xlarge",
      "i3.2xlarge",
      "i3.4xlarge"
    ],
    "defaultValue": "i3.2xlarge"
  },
  "driver_node_type_id": {
    "type": "fixed",
    "value": "i3.2xlarge",
    "hidden": true
  },
  "autoscale.min_workers": {
    "type": "fixed",
    "value": 1,
    "hidden": true
  },
  "autoscale.max_workers": {
    "type": "range",
    "maxValue": 25,
    "defaultValue": 5
  },
  "enable_elastic_disk": {
    "type": "fixed",
    "value": true,
    "hidden": true
  },
  "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": "i3.xlarge",
    "hidden": true
  },
  "driver_node_type_id": {
    "type": "fixed",
    "value": "i3.xlarge",
    "hidden": true
  },
  "spark_version": {
    "type": "fixed",
    "value": "auto:latest-ml",
    "hidden": true
  },
  "enable_elastic_disk": {
    "type": "fixed",
    "value": false,
    "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": "[rmci][3-5][rnad]*.[0-8]{0,1}xlarge"
  },
  "driver_node_type_id": {
    "type": "regex",
    "pattern": "[rmci][3-5][rnad]*.[0-8]{0,1}xlarge"
  },
  "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" ]}}