Referencia de directiva de proceso

  • Artículo

Este artículo es una referencia para las definiciones de directivas de proceso. Los artículos incluyen una referencia de los atributos de directiva disponibles y los tipos de limitación. También hay directivas de ejemplo que puede usar como referencia para casos de uso comunes.

¿Qué son las definiciones de directiva?

Las definiciones de directiva son reglas de directiva individuales expresadas en JSON. Una definición puede agregar una regla a cualquiera de los atributos controlados con la API de clústeres. Por ejemplo, estas definiciones establecen un tiempo de autoterminación predeterminado, prohíben a los usuarios usar grupos y aplican el 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
  }
}

Solo puede haber una limitación por atributo. Una ruta de acceso del atributo refleja el nombre del atributo de API. Para atributos anidados, la ruta de acceso concatena los nombres de los atributos anidados mediante puntos. No se limitarán los atributos que no se definan en una definición de directiva.

Atributos compatibles

Las directivas admiten todos los atributos controlados con la API de clústeres. El tipo de restricciones que puede colocar en los atributos varía según su tipo y relación con los elementos de la interfaz de usuario. No se pueden usar directivas para definir permisos de proceso.

También puede usar directivas para establecer las DBU máximas por hora y tipo de clúster. Consulte Rutas de acceso de atributos virtuales.

En la tabla siguiente, se enumeran las rutas de acceso al atributo de directiva admitidas:

Ruta de acceso al atributo Tipo Descripción
autoscale.max_workers número opcional Si está oculto, quita el campo de número máximo de trabajos de la interfaz de usuario.
autoscale.min_workers número opcional Si está oculto, quita el campo de número mínimo de trabajos de la interfaz de usuario.
autotermination_minutes number Un valor de 0 representa que no hay terminación automática. Si está oculto, quita la casilla de terminación automática y la entrada de valor de la interfaz de usuario.
azure_attributes.availability string Controla que el proceso usa instancias a petición o de acceso puntual (ON_DEMAND_AZURE o SPOT_WITH_FALLBACK_AZURE).
azure_attributes.first_on_demand number Controla el número de nodos que se van a colocar en instancias a petición.
azure_attributes.spot_bid_price_percent number Controla el precio máximo de las instancias de acceso puntual de Azure.
cluster_log_conf.path string Dirección URL de destino de los archivos de registro.
cluster_log_conf.type string Tipo de destino del registro. DBFS es el único valor aceptable.
cluster_name string El nombre del clúster.
custom_tags.* string Controla los valores de etiqueta específicos anexando el nombre de la etiqueta, por ejemplo: custom_tags.<mytag>.
data_security_mode string Establece el modo de acceso del clúster. Unity Catalog requiere SINGLE_USER o USER_ISOLATION (modo de acceso compartido en la interfaz de usuario). Un valor de NONE significa que no hay ninguna característica de seguridad habilitada.
docker_image.basic_auth.password string Contraseña de la autenticación básica de la imagen de Databricks Container Services.
docker_image.basic_auth.username string Nombre de usuario de la autenticación básica de la imagen de Databricks Container Services.
docker_image.url string Controle la dirección URL de la imagen de Databricks Container Services. Si está oculto, quita la sección Databricks Container Services de la interfaz de usuario.
driver_node_type_id cadena opcional Si está oculto, quita la selección del tipo de nodo de controlador de la interfaz de usuario.
enable_local_disk_encryption boolean Establézcalo en true para habilitar o en false para deshabilitar el cifrado de los discos que están conectados localmente al clúster (tal como se especifica mediante la API).
init_scripts.*.workspace.destination init_scripts.*.volumes.destination init_scripts.*.abfss.destination init_scripts.*.file.destination string * hace referencia al índice del script de inicialización en la matriz de atributos. Consulte Escritura de directivas para atributos de matriz.
instance_pool_id cadena Controla el grupo que utilizan los nodos de trabajo si driver_instance_pool_id también está definido o, en caso contrario, para todos los nodos de clúster. Si utiliza grupos para los nodos de trabajo, también debe utilizar grupos para el nodo de controlador. Si está oculto, quita la selección de grupo de la interfaz de usuario.
driver_instance_pool_id string Si se especifica, configura un grupo para el nodo de controlador distinto del configurado para los nodos de trabajo. Si no se especifica, hereda instance_pool_id. Si utiliza grupos para los nodos de trabajo, también debe utilizar grupos para el nodo de controlador. Si está oculto, quita la selección del grupo de controladores de la interfaz de usuario.
node_type_id string Si está oculto, quita la selección del tipo de nodo de trabajo de la interfaz de usuario.
num_workers número opcional Si está oculto, quita la especificación del número de trabajos de la interfaz de usuario.
runtime_engine string Determina si el clúster usa Photon o no. Los valores posibles son PHOTON o STANDARD.
single_user_name string Nombre de usuario del acceso de usuario único mediante transferencia de credenciales.
spark_conf.* cadena opcional Controla valores específicos de configuración anexando el nombre de clave de configuración, por ejemplo: spark_conf.spark.executor.memory.
spark_env_vars.* cadena opcional Controla valores específicos de variables de entorno de Spark anexando la variable de entorno, por ejemplo: spark_env_vars.<environment variable name>.
spark_version string El nombre de la versión de la imagen de Spark tal como se especifica a través de la API (Databricks Runtime). También puede usar valores de directiva especiales que seleccionen dinámicamente Databricks Runtime. Vea Valores de directiva especiales para la selección de Databricks Runtime.
workload_type.clients.jobs boolean Define si el recurso de proceso se puede usar para trabajos. Consulte Impedir que el proceso se use con trabajos.
workload_type.clients.notebooks boolean Define si el recurso de proceso se puede usar con cuadernos. Consulte Impedir que el proceso se use con trabajos.

Rutas de acceso de atributos virtuales

En esta tabla se incluyen dos atributos sintéticos adicionales admitidos por las directivas:

Ruta de acceso al atributo Tipo Description
dbus_per_hour number Atributo calculado que representa el número máximo de DBU que un recurso puede usar cada hora, incluido el nodo de controlador. Esta métrica es una manera directa de controlar el costo en el nivel de proceso individual. Uso con limitación de intervalo.
cluster_type cadena Representa el tipo de clúster que se puede crear:

* all-purpose para procesos multiuso de Azure Databricks
* job para procesos de trabajo creados por el programador de trabajos
* dlt para procesos creados para canalizaciones de Delta Live Tables

Permite o impide la creación de tipos especificados de procesos a partir de la directiva. Si no se permite el valor all-purpose, la directiva no se muestra en la interfaz de usuario de proceso de creación de todo el propósito. Si no se permite el valor job, la directiva no se muestra en la interfaz de usuario de proceso del trabajo de creación.

Valores de directiva especiales para la selección de Databricks Runtime

El atributo spark_version admite valores especiales que se asignan dinámicamente a una versión de Databricks Runtime basada en el conjunto actual de versiones admitidas de Databricks Runtime.

Los siguientes valores se pueden usar en el atributo spark_version:

  • auto:latest: Se asigna a la versión más reciente de Databricks Runtime.
  • auto:latest-ml: Se asigna a la versión más reciente de Databricks Runtime ML.
  • auto:latest-lts: Se asigna a la versión más reciente de Databricks Runtime de soporte técnico a largo plazo (LTS).
  • auto:latest-lts-ml: Se asigna a la versión más reciente de ML de LTS Databricks Runtime.
  • auto:prev-major: Se asigna a la segunda versión más reciente del entorno de ejecución de Databricks. Por ejemplo, si auto:latest es 14.2, auto:prev-major es 13.3.
  • auto:prev-major-ml: Se asigna a la segunda versión más reciente de Databricks Runtime ML. Por ejemplo, si auto:latest es 14.2, auto:prev-major es 13.3.
  • auto:prev-lts: Se asigna a la segunda versión más reciente de LTS Databricks Runtime. Por ejemplo, si auto:latest-lts es 13.3, auto:prev-lts es 12.2.
  • auto:prev-lts-ml: Se asigna a la segunda versión de ML de LTS Databricks Runtime más reciente. Por ejemplo, si auto:latest-lts es 13.3, auto:prev-lts es 12.2.

Nota:

El uso de estos valores no hace que el proceso se actualice automáticamente cuando se publique una nueva versión en tiempo de ejecución. Un usuario debe editar explícitamente el proceso para que cambie la versión de Databricks Runtime.

Tipos de directivas admitidas

En esta sección se incluye una referencia para cada uno de los tipos de directiva disponibles. Hay dos categorías de tipos de directiva: directivas fijas y directivas de limitación.

Las directivas fijas impiden la configuración del usuario en un atributo. Los dos tipos de directivas fijas son:

Limitar las directivas también limita las opciones de un usuario para configurar un atributo. Las directivas de limitación permiten además establecer valores predeterminados y hacer que los atributos sean opcionales. Consulte campos de directiva de limitación adicional.

Las opciones para limitar directivas son:

Directiva fija

Las directivas fijas limitan el atributo al valor especificado. Para los valores de atributo que no sean numéricos y booleanos, el valor debe representarse mediante una cadena o poder convertirse a una cadena.

Con directivas fijas, también puede ocultar el atributo de la interfaz de usuario. Para ello establezca el campo hidden en true.

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

Esta directiva de ejemplo corrige la versión de Databricks Runtime y oculta el campo de la UI del usuario:

{
  "spark_version": { "type": "fixed", "value": "auto:latest-lts", "hidden": true }
}

Directiva de prohibición

Una directiva de prohibición impide que los usuarios configuren un atributo. Las directivas de prohibición solo son compatibles con atributos opcionales.

interface ForbiddenPolicy {
    type: "forbidden";
}

Esta directiva prohíbe adjuntar grupos al proceso para los nodos de trabajo. Los grupos también están prohibidos para el nodo de controlador, porque driver_instance_pool_id hereda la directiva.

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

Directiva de lista de permitidos

Una directiva de lista de permitidos especifica una lista de valores entre los que el usuario puede elegir al configurar un atributo.

interface AllowlistPolicy {
  type: "allowlist";
  values: (string | number | boolean)[];
  defaultValue?: string | number | boolean;
  isOptional?: boolean;
}

Este ejemplo de lista de permitidos permite al usuario seleccionar entre dos versiones de Databricks Runtime:

{
  "spark_version":  { "type": "allowlist", "values": [ "13.3.x-scala2.12", "12.2.x-scala2.12" ] }
}

Directiva de lista de bloqueados

La directiva de lista de bloqueados enumera los valores no permitidos. Como los valores deben ser coincidencias exactas, es posible que esta directiva no funcione según lo previsto cuando el atributo es flexible en cuanto a cómo se representa el valor (por ejemplo, si permite espacios iniciales o finales).

interface BlocklistPolicy {
  type: "blocklist";
  values: (string | number | boolean)[];
  defaultValue?: string | number | boolean;
  isOptional?: boolean;
}

En este ejemplo se impide que el usuario seleccione 7.3.x-scala2.12 como Databricks Runtime.

{
  "spark_version":  { "type": "blocklist", "values": [ "7.3.x-scala2.12" ] }
}

Directiva de expresión regular

Una directiva de expresión limita los valores disponibles a aquellos que coincidan con la expresión regular. Por motivos de seguridad, asegúrese de que la expresión regular esté anclada al principio y al final del valor de cadena.

interface RegexPolicy {
  type: "regex";
  pattern: string;
  defaultValue?: string | number | boolean;
  isOptional?: boolean;
}

En este ejemplo se limitan las versiones de Databricks Runtime que puede seleccionar un usuario:

{
  "spark_version":  { "type": "regex", "pattern": "13\\.[3456].*" }
}

Directiva de intervalo

Una directiva de intervalo limita el valor a un intervalo especificado mediante los campos minValue y maxValue. El valor debe ser un número decimal. Los límites numéricos se deben poder representar como un valor de número de punto flotante doble. Para indicar que falta un límite específico, puede omitir minValue o maxValue.

interface RangePolicy {
  type: "range";
  minValue?: number;
  maxValue?: number;
  defaultValue?: string | number | boolean;
  isOptional?: boolean;
}

En este ejemplo se limita la cantidad máxima de trabajos a 10:

{
  "num_workers":  { "type": "range", "maxValue": 10 }
}

Directiva no limitada

La directiva no limitada se usa para hacer que los atributos sean necesarios o para establecer el valor predeterminado en la interfaz de usuario.

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

En este ejemplo se agrega la etiqueta COST_BUCKET al proceso:

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

Este otro ejemplo permite establecer un valor predeterminado para una variable de configuración de Spark, pero también omitirlo (quitarlo):

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

Campos de directiva de limitación adicionales

En una directiva de limitación, puede especificar dos campos adicionales:

  • defaultValue: un valor que se rellena automáticamente en la interfaz de usuario de proceso de creación.
  • isOptional: una directiva de limitación en un atributo hace automáticamente que este sea obligatorio. Para que el atributo sea opcional, establezca el campo isOptional en true.

Nota:

Los valores predeterminados no se aplican automáticamente a los procesos creados con la API de clústeres. Para aplicar valores predeterminados mediante la API, agregue el parámetro apply_policy_default_values a la definición de proceso y establézcalo en true.

Esta directiva de ejemplo especifica el valor predeterminado id1 para el grupo para los nodos de trabajo, pero lo convierte en opcional. Al crear el proceso, puede seleccionar un grupo diferente o elegir no usar uno. Si driver_instance_pool_id no se define en la directiva o al crear el proceso, se utiliza el mismo grupo para los nodos de trabajo y el nodo de controlador.

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

Escritura de directivas para atributos de matriz

Puede especificar directivas para los atributos de matriz de dos maneras:

  • Limitaciones genéricas para todos los elementos de matriz. Estas limitaciones utilizan el símbolo comodín * en la ruta de acceso a la directiva.
  • Limitaciones específicas para un elemento de matriz en un índice específico. Estas limitaciones utilizan un número en la ruta de acceso.

Por ejemplo, para el atributo de matriz init_scripts, las rutas de acceso genéricas comienzan por init_scripts.* y las rutas de acceso específicas, por init_scripts.<n>, donde <n> es un índice entero en la matriz (que comienza por 0). Puede combinar las limitaciones genéricas y las específicas, y en ese caso, la limitación genérica se aplica a cada elemento de matriz que no tiene una limitación específica. En cada caso, solo se aplicará una limitación de directiva.

En las secciones siguientes se muestran ejemplos comunes que usan atributos de matriz.

Requerir entradas específicas de inclusión

No puede exigir valores específicos sin especificar el orden. Por ejemplo:

{
  "init_scripts.0.volumes.destination": {
    "type": "fixed",
    "value": "<required-script-1>"
  },
  "init_scripts.1.volumes.destination": {
    "type": "fixed",
    "value": "<required-script-2>"
  }
}

Requerir un valor fijo de toda la lista

{
  "init_scripts.0.volumes.destination": {
    "type": "fixed",
    "value": "<required-script-1>"
  },
  "init_scripts.*.volumes.destination": {
    "type": "forbidden"
  }
}

Prohibir completamente el uso

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

Permitir entradas que siguen restricciones específicas

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

Corregir un conjunto específico de scripts de inicialización

En el caso de las rutas de acceso init_scripts, la matriz puede contener una de varias estructuras para las que pueda ser necesario controlar todas las variantes en función del caso de uso. Por ejemplo, para exigir un conjunto específico de scripts de inicialización y prohibir cualquier variante de la otra versión, puede usar el patrón siguiente:

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

Ejemplos de directivas

En esta sección se incluyen ejemplos de directivas que puede usar como referencia para crear sus propias directivas. También puede usar las familias de directivas proporcionadas por Azure Databricks como plantillas para casos de uso de directivas comunes.

Directiva de proceso general

Una directiva de proceso de uso general pensada para guiar a los usuarios y restringir ciertas funcionalidades, al tiempo que exige etiquetas, restringe el número máximo de instancias y aplica el tiempo de espera.

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

Definición de límites en procesos de canalización de Delta Live Tables

Nota:

Al usar directivas para configurar el proceso de Delta Live Tables, Databricks recomienda aplicar una sola directiva al proceso de default y maintenance.

Para configurar una directiva para un proceso de canalización, cree una directiva con el campo cluster_type establecido en dlt. En el ejemplo siguiente se crea una directiva mínima para un proceso de 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
  }
}

Directiva simple de tamaño medio

Permite a los usuarios crear un proceso de tamaño medio con una configuración mínima. El único campo obligatorio en el momento de la creación es el nombre del proceso; el resto está fijo y 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"
  }
}

Directiva de solo trabajo

Permite a los usuarios crear un proceso de trabajo para ejecutar trabajos. Con esta directiva, los usuarios no pueden crear un proceso multiuso.

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

Directiva de metastore externo

Permite a los usuarios crear un proceso con un metastore definido por el administrador ya adjunto. Esto es útil para permitir a los usuarios crear sus propios procesos sin necesidad de configuración 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 el proceso se use con trabajos

Esta directiva impide que los usuarios usen el proceso para ejecutar trabajos. Los usuarios solo podrán usar el proceso con cuadernos.

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

Eliminar la directiva de escalado automático

Esta directiva deshabilita el escalado automático y permite al usuario establecer el número de trabajos dentro de un intervalo determinado.

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

Cumplimiento de etiquetas personalizadas

Para agregar una regla de etiqueta de proceso a una directiva, use el atributo custom_tags.<tag-name>.

Por ejemplo, cualquier usuario que use esta directiva debe rellenar una etiqueta de COST_CENTER con 9999, 9921 o 9531 para que se inicie el proceso:

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