Scripts de inicialización de nodos de clúster

Un script de inicialización es un script de shell que se ejecuta durante el inicio de cada nodo de un clúster antes de que se inicie el entorno JVM de trabajo o el controlador de Apache Spark.

Los siguientes son algunos ejemplos de tareas realizadas por scripts de inicialización:

• Instalar paquetes y bibliotecas no incluidos en Databricks Runtime. Para instalar paquetes de Python, use el archivo binario pip de Azure Databricks que se encuentra en /databricks/python/bin/pip para asegurarse de que los paquetes de Python se instalan en el entorno virtual de Python de Azure Databricks en lugar del entorno de Python del sistema. Por ejemplo, /databricks/python/bin/pip install <package-name>.
• Modificar el valor de classpath del sistema de JVM en casos especiales.
• Establecer las propiedades del sistema y las variables de entorno que utiliza JVM.
• Modificar los parámetros de configuración de Spark.

Advertencia

Azure Databricks examina la ubicación reservada /databricks/init de los scripts de inicialización globales heredados que están habilitados en nuevas áreas de trabajo de forma predeterminada. Databricks le recomienda evitar almacenar scripts de inicialización en esta ubicación para evitar un comportamiento inesperado.

Tipos de scripts de inicialización

Azure Databricks admite dos tipos de scripts de inicialización: de ámbito de clúster y globales.

• De ámbito de clúster: se ejecutan en todos los clústeres configurados con el script. Esta es la manera recomendada para ejecutar un script de inicialización.
• Globales: se ejecutan en todos los clústeres del área de trabajo. Pueden ayudar a aplicar configuraciones de clúster coherentes en el área de trabajo. Úselos con cuidado, porque pueden producir efectos imprevistos, como conflictos de bibliotecas. Solo los usuarios administradores pueden crear scripts de inicialización globales. Los scripts de inicialización globales no se ejecutan en clústeres de Model Serving.

Nota

Hay dos tipos de scripts de inicialización que están en desuso. Debe migrar los scripts de inicialización de estos tipos a los que se indican en los párrafos anteriores:

• Con el nombre del clúster: se ejecutan en un clúster con el mismo nombre que el script. Los scripts de inicialización con el nombre del clúster hacen todo lo posible para que el proceso de inicialización continúe (ignoran los errores de manera silenciosa). En su lugar, se deben usar scripts de inicialización de ámbito de clúster, que son un reemplazo completo.
• Globales heredados: se ejecutan en todos los clústeres. Son menos seguros que el nuevo marco de scripts de inicialización global, ignoran los errores de forma silenciosa y no pueden hacer referencia a variables de entorno. Los scripts de inicialización globales heredados que se tengan deben migrarse al nuevo marco de scripts de inicialización global. Consulte Migración de los scripts de inicialización globales heredados a los nuevos.

Siempre que cambie cualquier tipo de script de inicialización, debe reiniciar todos los clústeres afectados por el script.

Orden de ejecución de los scripts de inicialización

El orden de ejecución de los scripts de inicialización es:

1. Globales heredados (en desuso)
2. Con el nombre del clúster (en desuso)
3. Globales (nuevo)
4. De ámbito de clúster

Variables de entorno

Los scripts de inicialización globales y de ámbito de clúster admiten las siguientes variables de entorno:

• DB_CLUSTER_ID: id. del clúster en el que se ejecuta el script. Consulte API Clusters 2.0.
• DB_CONTAINER_IP: dirección IP privada del contenedor en el que se ejecuta Spark. El script de inicialización se ejecuta dentro de este contenedor. Consulte SparkNode.
• DB_IS_DRIVER: indica si el script se ejecuta en un nodo de controlador.
• DB_DRIVER_IP: dirección IP del nodo de controlador.
• DB_INSTANCE_TYPE: tipo de instancia de la máquina virtual del host.
• DB_CLUSTER_NAME: nombre del clúster en el que se ejecuta el script.
• DB_IS_JOB_CLUSTER: indica si el clúster se creó para ejecutar un trabajo. Consulte Creación de un trabajo.

Por ejemplo, si desea ejecutar parte de un script solo en un nodo de controlador, podría escribir un script como el siguiente:

echo $DB_IS_DRIVER
if [[ $DB_IS_DRIVER = "TRUE" ]]; then
  <run this part only on driver>
else
  <run this part only on workers>
fi
<run this part on both driver and workers>

También puede configurar variables de entorno personalizadas para un clúster y hacer referencia a esas variables en scripts de inicialización.

Uso de secretos en variables de entorno

Puede usar cualquier nombre de variable válido al hacer referencia a un secreto. El acceso a los secretos a los que se hace referencia en las variables de entorno viene determinado por los permisos del usuario que configuró el clúster. Todos los usuarios del clúster pueden acceder a los secretos almacenados en variables de entorno, pero se censuran de la presentación de texto no cifrado de la manera convencional, como los secretos a los que se hace referencia desde otro lugar.

Para más información, consulte Referencia a un secreto en una variable de entorno.

Registro

Los eventos de inicio y finalización de scripts de inicialización se capturan en registros de eventos de clúster. Los detalles se capturan en registros de clúster. Los eventos de creación, edición y eliminación de scripts de inicialización globales también se capturan en registros de diagnóstico a nivel de cuenta.

Eventos de scripts de inicialización

Los registros de eventos de clúster capturan dos eventos de scripts de inicialización: INIT_SCRIPTS_STARTED y INIT_SCRIPTS_FINISHED, que indican qué scripts están programados para su ejecución y cuáles se han completado correctamente. INIT_SCRIPTS_FINISHED también captura la duración de la ejecución.

Los scripts de inicialización globales se indican en los detalles de los eventos en los registros con la clave "global", y los scripts de inicialización de ámbito de clúster se indican con la clave "cluster".

Nota

Los registros de eventos de clúster no recogen eventos de scripts de inicialización de cada nodo del clúster; se selecciona un único nodo para representarlos a todos.

Registros de scripts de inicialización

Si se configura la entrega de registros de clúster para un clúster, los registros de scripts de inicialización se escriben en /<cluster-log-path>/<cluster-id>/init_scripts. Los registros de cada contenedor del clúster se escriben en un subdirectorio denominado init_scripts/<cluster_id>_<container_ip>. Por ejemplo, si cluster-log-path se establece en cluster-logs, la ruta de acceso a los registros de un contenedor específico sería: dbfs:/cluster-logs/<cluster-id>/init_scripts/<cluster_id>_<container_ip>.

Si el clúster está configurado para escribir los registros en DBFS, puede verlos con la utilidad del sistema de archivos (dbutils.fs) o con la CLI de DBFS. Por ejemplo, si el id. del clúster es 1001-234039-abcde739:

dbfs ls dbfs:/cluster-logs/1001-234039-abcde739/init_scripts

1001-234039-abcde739_10_97_225_166
1001-234039-abcde739_10_97_231_88
1001-234039-abcde739_10_97_244_199

dbfs ls dbfs:/cluster-logs/1001-234039-abcde739/init_scripts/1001-234039-abcde739_10_97_225_166

<timestamp>_<log-id>_<init-script-name>.sh.stderr.log
<timestamp>_<log-id>_<init-script-name>.sh.stdout.log

Cuando no se configura la entrega de registros de clúster, los registros se escriben en /databricks/init_scripts. Puede usar comandos de shell estándar en un cuaderno para enumerar y ver los registros:

%sh
ls /databricks/init_scripts/
cat /databricks/init_scripts/<timestamp>_<log-id>_<init-script-name>.sh.stdout.log

Cada vez que se inicia un clúster, escribe un registro en la carpeta de registros del script de inicialización.

Importante

Cualquier usuario que cree un clúster y habilite la entrega de registros del clúster puede ver la salida de stderr y stdout de los scripts de inicialización globales. Debe asegurarse de que los scripts de inicialización globales no devuelvan ninguna información confidencial.

Registros de diagnóstico

Los registros de diagnóstico de Azure Databricks capturan los eventos de creación, edición y eliminación de scripts de inicialización globales en el tipo de evento globalInitScripts. Consulte Registro de diagnóstico en Azure Databricks.

Scripts de inicialización de ámbito de clúster

Los scripts de inicialización de ámbito de clúster son scripts de inicialización definidos en una configuración de clúster. Los scripts de inicialización de ámbito de clúster se aplican tanto a los clústeres que crea el usuario como a los que se crean para ejecutar trabajos. Puesto que los scripts forman parte de la configuración del clúster, el control de acceso al clúster permite controlar quién puede cambiar los scripts.

Puede configurar scripts de inicialización de ámbito de clúster con la interfaz de usuario, la CLI y mediante la invocación de la API Clusters. Esta sección se centra en la realización de estas tareas desde la interfaz de usuario. Para los demás métodos, consulte Configuración y documentación de la CLI de Databricks y Clusters API 2.0.

Puede agregar cualquier número de scripts y se ejecutan secuencialmente en el orden proporcionado.

Si un script de inicialización de ámbito de clúster devuelve un código de salida distinto de cero, se produce un error al iniciar el clúster. Para solucionar problemas en los scripts de inicialización de ámbito de clúster, puede configurar la entrega de registros de clúster y examinar el registro del script de inicialización.

Ubicaciones de los scripts de inicialización de ámbito de clúster

Puede poner los scripts de inicialización en un directorio de DBFS o ADLS al que tenga acceso un clúster. Los scripts de inicialización de nodo de clúster en DBFS deben almacenarse en la raíz de DBFS. Azure Databricks no admite el almacenamiento de scripts de inicialización en un directorio de DBFS creado mediante el montaje de almacenamiento de objetos.

Ejemplos de scripts de inicialización de ámbito de clúster

En esta sección, se muestran dos ejemplos de scripts de inicialización.

Ejemplo: Instalación del controlador JDBC de PostgreSQL

Los siguientes fragmentos de código se ejecutan en un cuaderno de Python y crean un script de inicialización que instala un controlador JDBC de PostgreSQL.

1. Cree un directorio de DBFS en el que quiera almacenar el script de inicialización. En este ejemplo se usa dbfs:/databricks/scripts.

   dbutils.fs.mkdirs("dbfs:/databricks/scripts/")
   

2. Cree un script denominado postgresql-install.sh en ese directorio:

   dbutils.fs.put("/databricks/scripts/postgresql-install.sh","""
   #!/bin/bash
   wget --quiet -O /mnt/driver-daemon/jars/postgresql-42.2.2.jar https://repo1.maven.org/maven2/org/postgresql/postgresql/42.2.2/postgresql-42.2.2.jar""", True)
   

3. Compruebe que el script existe.

   display(dbutils.fs.ls("dbfs:/databricks/scripts/postgresql-install.sh"))
   

Como alternativa, puede crear el script de inicialización postgresql-install.sh de manera local:

#!/bin/bash
wget --quiet -O /mnt/driver-daemon/jars/postgresql-42.2.2.jar https://repo1.maven.org/maven2/org/postgresql/postgresql/42.2.2/postgresql-42.2.2.jar

y copiarlo en dbfs:/databricks/scripts por medio de la CLI de DBFS:

dbfs cp postgresql-install.sh dbfs:/databricks/scripts/postgresql-install.sh

Ejemplo: Uso de Conda para instalar bibliotecas de Python

Con Databricks Runtime 9.0 y versiones posteriores, no se puede usar Conda para instalar bibliotecas de Python. Para obtener instrucciones sobre cómo instalar paquetes de Python en un clúster, consulte Bibliotecas.

Importante

Anaconda Inc. actualizó sus términos del servicio para los canales de anaconda.org en septiembre de 2020. Según los nuevos términos del servicio, puede necesitar una licencia comercial si depende del empaquetado y la distribución de Anaconda. Consulte las preguntas más frecuentes sobre Anaconda Commercial Edition para obtener más información. El uso de cualquier canal de Anaconda se rige por sus términos del servicio.

Como resultado de este cambio, Databricks ha quitado la configuración de canal predeterminada para el administrador de paquetes de Conda. Éste es un cambio importante. Debe actualizar el uso de los comandos de Conda en los scripts de inicialización para especificar un canal con -c. Si no especifica ningún canal, los comandos de Conda producirán un error con PackagesNotFoundError.

En Databricks Runtime 8.4 ML y versiones anteriores, se usa el administrador de paquetes Conda para instalar paquetes de Python. Para instalar una biblioteca de Python al inicializar un clúster, puede usar un script como el siguiente:

#!/bin/bash
set -ex
/databricks/python/bin/python -V
. /databricks/conda/etc/profile.d/conda.sh
conda activate /databricks/python
conda install -c conda-forge -y astropy

Configuración de un script de inicialización de ámbito de clúster

Puede configurar un clúster para ejecutar un script de inicialización mediante la interfaz de usuario o la API.

Importante

• El script debe estar en la ubicación configurada. Si no está el script, el clúster no se iniciará o se escalará verticalmente de forma automática.
• El script de inicialización no puede tener más de 64 KB. Si un script supera ese tamaño, el clúster no se iniciará y aparecerá un mensaje de error en el registro del clúster.

Configuración de un script de inicialización de ámbito de clúster mediante la interfaz de usuario

Para usar la página de configuración de un clúster para configurarlo de modo que ejecute un script de inicialización:

1. En la página de configuración del clúster, haga clic en el botón de alternancia Advanced Options (Opciones avanzadas).

2. En la parte inferior de la página, haga clic en la pestaña Init Scripts (Scripts de inicialización).

   

3. En la lista desplegable Destination (Destino), seleccione un tipo de destino. En el ejemplo de la sección anterior, el destino es DBFS.

4. Especifique la ruta de acceso al script de inicialización. En el ejemplo de la sección anterior, la ruta de acceso es dbfs:/databricks/scripts/postgresql-install.sh. La ruta de acceso debe comenzar con dbfs:/.

5. Haga clic en Agregar.

Para quitar un script de la configuración del clúster, haga clic en el icono a la derecha del script. Cuando confirme la eliminación, se le pedirá que reinicie el clúster. Opcionalmente, puede eliminar el archivo de script de la ubicación en la que lo cargó.

Configuración de un script de inicialización de ámbito de clúster mediante la API REST de DBFS

Para usar la API Clusters 2.0 con el fin de configurar el clúster con el id. 1202-211320-brick1 para que ejecute el script de inicialización de la sección anterior, ejecute el siguiente comando:

curl -n -X POST -H 'Content-Type: application/json' -d '{
  "cluster_id": "1202-211320-brick1",
  "num_workers": 1,
  "spark_version": "7.3.x-scala2.12",
  "node_type_id": "Standard_D3_v2",
  "cluster_log_conf": {
    "dbfs" : {
      "destination": "dbfs:/cluster-logs"
    }
  },
  "init_scripts": [ {
    "dbfs": {
      "destination": "dbfs:/databricks/scripts/postgresql-install.sh"
    }
  } ]
}' https://<databricks-instance>/api/2.0/clusters/edit

Scripts de inicialización globales

Un script de inicialización global se ejecuta en todos los clústeres creados en el área de trabajo. Los scripts de inicialización globales son útiles cuando se quiere aplicar configuraciones de bibliotecas o pantallas de seguridad en toda la organización. Solo los administradores pueden crear scripts de inicialización globales. Puede crearlos con la interfaz de usuario o con la API REST.

Importante

Use los scripts de inicialización globales con cuidado:

• Es fácil agregar bibliotecas o realizar otras modificaciones que causen efectos imprevistos. Siempre que sea posible, use scripts de inicialización de ámbito de clúster.
• Cualquier usuario que cree un clúster y habilite la entrega de registros del clúster puede ver la salida de stderr y stdout de los scripts de inicialización globales. Debe asegurarse de que los scripts de inicialización globales no devuelvan ninguna información confidencial.

Para solucionar problemas en los scripts de inicialización globales, puede configurar la entrega de registros de clúster y examinar el registro del script de inicialización.

Adición de un script de inicialización global mediante la interfaz de usuario

Para configurar scripts de inicialización globales mediante la consola de administración:

1. Vaya a la consola de administración y haga clic en la pestaña Global Init Scripts (Scripts de inicialización globales).

   

2. Haga clic en + Agregar.

3. Asigne un nombre al script y, para especificarlo, escriba, pegue o arrastre un archivo de texto al campo Script.

   

   Nota

   El script de inicialización no puede tener más de 64 KB. Si un script supera ese tamaño, aparece un mensaje de error al intentar guardar.

4. Si tiene más de un script de inicialización global configurado para el área de trabajo, establezca el orden en el que se ejecutará el nuevo script.

5. Si quiere que el script esté habilitado para todos los clústeres nuevos y reiniciados después de guardar, defina la opción en Habilitado.

   Importante

   Al agregar un script de inicialización global o hacer cambios en el nombre, el orden de ejecución o la habilitación de scripts de inicialización, esos cambios no surten efecto hasta que reinicie el clúster.

6. Haga clic en Agregar.

Incorporación de un script de inicialización global mediante Terraform

Puede agregar un script de inicialización global mediante el proveedor Terraform de Databricks y databricks_global_init_script.

Edición de un script de inicialización global mediante la interfaz de usuario

1. Vaya a la consola de administración y haga clic en la pestaña Global Init Scripts (Scripts de inicialización globales).
2. Haga clic en un script.
3. Edite el script.
4. Haga clic en Confirmar.

Configuración de un script de inicialización global mediante la API

Los administradores pueden agregar, eliminar y reordenar los scripts de inicialización globales, u obtener información sobre ellos, en el área de trabajo mediante la API Global Init Scripts 2.0.

Migración de los scripts de inicialización globales heredados a los nuevos

Si su área de trabajo de Azure Databricks se inició antes de agosto de 2020, es posible que todavía tenga scripts de inicialización globales heredados. Debe migrarlos al nuevo marco de scripts de inicialización globales para aprovechar las características de seguridad, coherencia y visibilidad incluidas en el nuevo marco de scripts.

1. Copie los scripts de inicialización globales heredados y agréguelos al nuevo marco de scripts de inicialización globales por medio de la interfaz de usuario o la API REST.

   Manténgalos deshabilitados hasta que haya completado el siguiente paso.

2. Deshabilite todos los scripts de inicialización globales heredados.

   En la consola de administración, vaya a la pestaña Global Init Scripts (Scripts de inicialización globales) y desactive el conmutador Legacy Global Init Scripts (Scripts de inicialización globales heredados).

   

3. Habilite los nuevos scripts de inicialización globales.

   En la pestaña Global Init Scripts (Scripts de inicialización globales), active el conmutador Enabled (Habilitado) para cada script de inicialización que quiera habilitar.

   

4. Reinicie todos los clústeres.

   • Los scripts heredados no se ejecutarán en los nodos nuevos que se agreguen durante el escalado vertical automatizado de los clústeres que están en ejecución. Tampoco se ejecutarán los nuevos scripts de inicialización globales en esos nodos nuevos. Debe reiniciar todos los clústeres para asegurarse de que los nuevos scripts se ejecuten en ellos y de que ningún clúster actual intente agregar nuevos nodos sin que se ejecuten en ellos los scripts globales.
   • Puede que sea necesario modificar los scripts no idempotentes al migrar al nuevo marco de scripts de inicialización globales y deshabilitar los scripts heredados.