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 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 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. Ver Caminhos de atributos virtuais.

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

Caminhos de atributos virtuais

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

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

O atributo spark_version suporta valores especiais que são mapeados 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 do Databricks Runtime com suporte de longo prazo (LTS).
• auto:latest-lts-ml: Corresponde à versão mais recente do Runtime ML do Databricks LTS.
• 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.

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 de 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 campo hidden como true.

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

Esta política de exemplo estabelece a versão do Databricks Runtime e oculta o campo da interface 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ó são compatíveis com atributos opcionais.

interface ForbiddenPolicy {
    type: "forbidden";
}

Esta política proíbe anexar pools aos nós de trabalho na infraestrutura de computação. 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, esta política pode não funcionar como esperado quando o atributo é flexível na forma como o valor é representado (por exemplo, permitindo espaços no início e no fim).

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 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 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 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 de criação de computação.
• 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.

Esta política de exemplo especifica o valor padrão id1 para o grupo de nós de trabalho, mas torna-o 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 unidade de computação, é utilizada a mesma pool para os 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 de política.
• Limitações específicas para um elemento de matriz em um índice específico. Essas limitações incluem 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, 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"
  }
}

Proibir o uso por completo

{
  "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 init_scripts, 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 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í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 de fornecidas pelo Azure Databricks como modelos para casos de uso de políticas comuns.

• Política geral de computação
• Definir limites nos recursos de computação do pipeline DLT
• Política simples de média dimensão
• Política de criação exclusiva de postos de trabalho
• Política de metastore externo
• Impedir que os recursos de computação sejam usados com tarefas
• Remover a política de dimensionamento automático
• Imposiçã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"
  }
}

Estabelecer limites nos recursos computacionais do pipeline DLT

Para configurar uma política para uma computação de fluxo contínuo, crie uma política com o campo cluster_type definido como dlt. O exemplo a seguir cria uma política mínima para uma computação DLT:

{
  "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 apenas 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 os recursos de computação sejam usados em tarefas

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

Imposição de etiquetas personalizadas

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

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

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