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:

Caminhos de atributos virtuais

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

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.

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.

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

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