Scripts de inicialização do nó de cluster

Um script init é um script de concha que funciona durante o arranque de cada nó de cluster antes do arranque do piloto ou trabalhador do Apache Spark JVM.

Alguns exemplos de tarefas executadas por scripts init incluem:

  • Instale pacotes e bibliotecas não incluídos no tempo de execução de databricks. Para instalar pacotes Python, utilize o binário Azure Databricks pip localizado para garantir que os /databricks/python/bin/pip pacotes Python se instalam no ambiente virtual Azure Databricks Python em vez do ambiente python do sistema. Por exemplo, /databricks/python/bin/pip install <package-name>.
  • Modificar o sistema JVM em casos especiais.
  • Definir propriedades do sistema e variáveis ambientais usadas pelo JVM.
  • Modificar os parâmetros de configuração da faísca.

Tipos de scripts init

A Azure Databricks suporta dois tipos de scripts init: cluster-scoped e global.

  • Âmbito de cluster: executar em todos os clusters configurados com o script. Esta é a maneira recomendada de executar um script init.
  • Global: correr em todos os clusters do espaço de trabalho. Eles podem ajudá-lo a impor configurações consistentes de cluster em todo o seu espaço de trabalho. Use-os cuidadosamente porque podem causar impactos inesperados, como conflitos de bibliotecas. Apenas os utilizadores de administração podem criar scripts init globais. Os scripts globais init não são executados em clusters de serviço de modelos.

Nota

Existem dois tipos de scripts init que são depreciados. Deve migrar scripts init destes tipos para os listados acima:

  • Com o nome de cluster: corra num cluster com o mesmo nome que o script. Os scripts init nomeados pelo cluster são o melhor esforço (ignorar silenciosamente falhas) e tentar continuar o processo de lançamento do cluster. Os scripts init de âmbito de cluster devem ser utilizados e são uma substituição completa.
  • Legado global: correr em todos os clusters. São menos seguros do que o novo quadro global de scripts init, ignoram silenciosamente falhas e não podem referenciar variáveis ambientais. Você deve migrar os scripts globais do legado existente para o novo quadro global init script. Ver Migrar do legado para novos scripts globais init.

Sempre que alterar qualquer tipo de script init, deve reiniciar todos os clusters afetados pelo script.

Init script ordem de execução

A ordem de execução dos scripts init é:

  1. Legado global (depreciado)
  2. Em grupo (precotado)
  3. Global (novo)
  4. Agrupados em cluster

Variáveis de ambiente

Os scripts init (nova geração) de cluster-scoped e globais suportam as seguintes variáveis ambientais:

  • DB_CLUSTER_ID: a identificação do cluster em que o guião está a decorrer. Ver Clusters API.
  • DB_CONTAINER_IP: o endereço IP privado do recipiente em que a Spark funciona. O guião inificado é executado dentro deste contentor. Ver SparkNode.
  • DB_IS_DRIVER: se o guião está a funcionar num nó condutor.
  • DB_DRIVER_IP: o endereço IP do nó do controlador.
  • DB_INSTANCE_TYPE: o tipo de instância do VM hospedeiro.
  • DB_CLUSTER_NAME: o nome do cluster em que o guião está a executar.
  • DB_PYTHON_VERSION: a versão de Python usada no cluster. Ver versão Python.
  • DB_IS_JOB_CLUSTER: se o cluster foi criado para gerir um emprego. Ver Criar um trabalho.
  • SPARKPASSWORD: um caminho para um segredo.

Por exemplo, se quiser executar parte de um script apenas num nó de condutor, pode escrever um guião como:

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>

Registo

Init script iniciar e terminar eventos são capturados em registos de eventos de cluster. Os detalhes são capturados em registos de agrupamentos. O script init global cria, edita e elimina eventos também são capturados em registos de diagnóstico ao nível da conta.

Init script eventos

Os registos de eventos de cluster capturam dois eventos de script init: INIT_SCRIPTS_STARTED INIT_SCRIPTS_FINISHED e, indicando quais scripts estão programados para execução e que completaram com sucesso. INIT_SCRIPTS_FINISHED também captura a duração da execução.

Os scripts init globais são indicados nos detalhes do evento de log pela chave "global" e os scripts init ins com âmbito de cluster são indicados pela chave "cluster" .

Nota

Os registos de eventos de cluster não registam eventos de script init para cada nó de cluster; apenas um nó é selecionado para representá-los todos.

Registos de script init

Se a entrega do registo de cluster estiver configurada para um cluster, os registos de script init são escritos para /<cluster-log-path>/<cluster-id>/init_scripts . Os registos de cada recipiente do cluster são escritos para uma subdirectória chamada init_scripts/<cluster_id>_<container_ip> . Por exemplo, se cluster-log-path for cluster-logs definido, o caminho para os troncos para um recipiente específico seria: dbfs:/cluster-logs/<cluster-id>/init_scripts/<cluster_id>_<container_ip> .

Se o cluster estiver configurado para escrever registos para dBFS, pode visualizar os registos utilizando o utilitário do sistema de ficheiros (dbutils.fs) ou o DBFS CLI. Por exemplo, se o ID do cluster 1001-234039-abcde739 for:

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

Quando a entrega do registo de cluster não está configurada, os registos são escritos para /databricks/init_scripts . Pode utilizar comandos de concha padrão num caderno para listar e visualizar os registos:

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

Sempre que um cluster é lançado, escreve um registo na pasta de registo de script init.

Importante

Qualquer utilizador que crie um cluster e permita a entrega de registos de cluster pode ver a stderr e a saída a partir de stdout scripts init globais. Deve garantir que os seus scripts init globais não produzam nenhuma informação sensível.

Registos de diagnóstico

O registo de diagnóstico Azure Databricks captura o script global init criar, editar e eliminar eventos sob o tipo de evento globalInitScripts . Consulte o registo de diagnóstico em Azure Databricks.

Scripts init com âmbito de cluster

Os scripts init de âmbito de cluster são scripts init definidos numa configuração de cluster. Os scripts init de âmbito de cluster aplicam-se tanto aos clusters que cria como aos criados para executar empregos. Uma vez que os scripts fazem parte da configuração do cluster, o controlo de acesso ao cluster permite-lhe controlar quem pode alterar os scripts.

Pode configurar scripts init com âmbito de cluster usando o UI, o CLI e invocando a API dos Clusters. Esta secção centra-se na realização destas tarefas utilizando a UI. Para obter outros métodos, consulte Databricks CLI e Clusters API.

Pode adicionar qualquer número de scripts, e os scripts são executados sequencialmente na ordem fornecida.

Se um script init com âmbito de cluster retornar um código de saída não zero, o lançamento do cluster falha. Pode resolver os scripts init com âmbito de cluster, configurando a entrega de registos de cluster e examinando o registo de script init.

Locais de script init com âmbito de cluster

Você pode colocar scripts init em um diretório DBFS ou ADLS acessível por um cluster. Os scripts de init do nó de cluster em DBFS devem ser armazenados na raiz DBFS. A Azure Databricks não suporta armazenar scripts init num diretório DBFS criado pela montagem de armazenamento de objetos.

Scripts init de âmbito de cluster de exemplo

Esta secção mostra dois exemplos de scripts init.

Exemplo: Instalar o controlador JDBC postgreSQL

Os seguintes snippets executados num portátil Python criam um script init que instala um controlador JDBC PostgreSQL.

  1. Crie um diretório DBFS onde pretende armazenar o script init. Este exemplo utiliza dbfs:/databricks/scripts.

    dbutils.fs.mkdirs("dbfs:/databricks/scripts/")
    
  2. Crie um guião nomeado postgresql-install.sh nesse diretório:

    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. Verifique se o guião existe.

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

Em alternativa, pode criar o roteiro init postgresql-install.sh localmente:

#!/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

e copiá-lo para dbfs:/databricks/scripts usar o DBFS CLI:

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

Exemplo: Use conda para instalar bibliotecas Python

No ML de execução de dados, utiliza o gestor de pacotes Conda para instalar pacotes Python. Para instalar uma biblioteca Python na inicialização do cluster, pode utilizar um script como o seguinte:

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

Nota

Para outras formas de instalar pacotes Python num cluster, consulte bibliotecas.

Configure um script init com âmbito de cluster

Pode configurar um cluster para executar um script init usando a UI ou API.

Importante

  • O script deve existir no local configurado. Se o script não existir, o cluster deixará de ser iniciado ou autodimensionado.
  • O script init não pode ser maior que 64KB. Se um script exceder esse tamanho, o cluster não será lançado e uma mensagem de falha aparecerá no registo de cluster.

Configure um script init com âmbito de cluster usando a UI

Para utilizar a página de configuração do cluster para configurar um cluster para executar um script init:

  1. Na página de configuração do cluster, clique nas opções avançadas para alternar.

  2. Na parte inferior da página, clique no separador Scripts Init.

    Separador Init Scripts

  3. No drop-down destino, selecione um tipo de destino. No exemplo da secção anterior, o destino é DBFS .

  4. Especifique um caminho para o roteiro init. No exemplo da secção anterior, o caminho é dbfs:/databricks/scripts/postgresql-install.sh . O caminho deve começar dbfs:/ com.

  5. Clique em Adicionar.

Para remover um script da configuração do cluster, clique na Eliminar ícone à direita do guião. Quando confirmar a eliminação, será solicitado que reinicie o cluster. Opcionalmente, pode eliminar o ficheiro de script do local para o quais o carregou.

Configure um script init com âmbito de cluster usando a API DBFS REST

Para utilizar a API clusters para configurar o cluster com ID 1202-211320-brick1 para executar o script init na secção anterior, executar o seguinte 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 init globais

Um script global init funciona em todos os clusters criados no seu espaço de trabalho. Os scripts globais init são úteis quando pretende impor configurações de bibliotecas em toda a organização ou ecrãs de segurança. Só os administradores podem criar scripts init globais. Pode criá-los utilizando a UI ou a REST API.

Importante

Use scripts globais init cuidadosamente:

  • É fácil adicionar bibliotecas ou fazer outras modificações que causam impactos inesperados. Sempre que possível, utilize scripts init com âmbito de cluster.
  • Qualquer utilizador que crie um cluster e permita a entrega de registos de cluster pode ver a stderr e a saída a partir de stdout scripts init globais. Deve garantir que os seus scripts init globais não produzam nenhuma informação sensível.

Pode resolver os scripts globais init configurando a entrega de registos de cluster e examinando o registo de script init.

Adicione um script init global usando o UI

Para configurar scripts globais init usando a Consola de Administração:

  1. Vá à Consola de Administração e clique no separador Scripts Global Init.

    Separador Global Init Scripts

  2. Clique no botão + Adicionar.

  3. Nomeie o script e introduza-o digitando, colando ou arrastando um ficheiro de texto para o campo Script.

    Adicionar script global init

    Nota

    O script init não pode ser maior que 64KB. Se um script exceder esse tamanho, aparecerá uma mensagem de erro quando tentar guardar.

  4. Se tiver mais do que um script init global configurado para o seu espaço de trabalho, deite a ordem na qual o novo script será executado.

  5. Se quiser que o script seja ativado para todos os clusters novos e reiniciados depois de guardar, alternar o interruptor Ativado.

    Importante

    Tem de reiniciar a execução de clusters para que as alterações aos scripts globais init produzam efeitos, incluindo alterações para executar o estado de ordem, nome e habilitação.

  6. Clique em Adicionar.

Editar um script init global usando o UI

  1. Vá à Consola de Administração e clique no separador Scripts Global Init.
  2. Clique num roteiro.
  3. Edite o guião.
  4. Clique em Confirmar.

Configurar um script init global usando a API

Os administradores podem adicionar, eliminar, reencaminizá-lo e obter informações sobre os scripts init globais no seu espaço de trabalho usando a API global Init Scripts.

Migrar do legado para novos scripts globais init

Se o seu espaço de trabalho Azure Databricks foi lançado antes de agosto de 2020, ainda poderá ter scripts init globais legados. Você deve migrar estes para o novo quadro global de script init para tirar partido das funcionalidades de segurança, consistência e visibilidade incluídas no novo quadro de scripts.

  1. Copie os seus scripts init global do seu legado existente e adicione-os à nova estrutura global de scripts init usando a UI ou a API REST.

    Mantenha-os desativado até completar o próximo passo.

  2. Desative todos os scripts init globais legados.

    Na Consola De Administração, vá ao separador Global Init Scripts e desligue o legacy Global Init Scripts Switch.

    Desativar os scripts globais init legacy

  3. Ativar os seus novos scripts init global.

    No separador Global Init Scripts, alternar no interruptor Ativado para cada script init que pretende ativar.

    Ativar scripts globais

  4. Reinicie todos os agrupamentos.

    • Os scripts legados não serão executados em novos nós adicionados durante a escala automatizada de clusters de execução. Nem novos scripts globais init serão executados nesses novos nós. Você deve reiniciar todos os clusters para garantir que os novos scripts funcionam sobre eles e que nenhum cluster existente tenta adicionar novos nós sem scripts globais em execução neles.
    • Scripts não-idempotentes podem ter de ser modificados quando migrar para o novo quadro global de scripts init e desativar scripts legados.