Usar scripts de inicialização com escopo de cluster

  • Artigo

Os scripts de inicialização no escopo do cluster são scripts de inicialização definidos em uma configuração de cluster. Eles se aplicam a ambos os clusters criados e aqueles criados para executar trabalhos.

Você pode configurar scripts de inicialização no escopo do cluster usando a interface do usuário ou a CLI e invocando a API de Clusters. Esta seção tem como foco a execução dessas tarefas por meio da interface do usuário. Para conferir outros métodos, consulte CLI do Databricks e API de Clusters.

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

Se um script de inicialização no escopo do cluster retornar um código de saída diferente de zero, a iniciação do cluster falhará. Solucione problemas de scripts de inicialização no escopo do cluster configurando a entrega de log do cluster e examinando o log do script de inicialização. Consulte Registro em log do script de inicialização.

Configurar um script de inicialização no escopo do cluster por meio da interface do usuário

Essa seção contém instruções para configurar um cluster para executar um script de inicialização usando a interface do usuário do Azure Databricks.

A Databricks recomenda gerenciar todos os scripts de inicialização como scripts de inicialização no escopo do cluster. Se você estiver usando a computação com o modo de acesso compartilhado ou de usuário único, armazene scripts de inicialização nos volumes do Catálogo do Unity. Se estiver usando a computação com modo de acesso compartilhado sem isolamento, utilize arquivos de espaço de trabalho para os scripts de inicialização.

Para o modo de acesso compartilhado, você deve adicionar scripts de inicialização ao allowlist. Consulte Bibliotecas de lista de permitidos e scripts de inicialização na computação compartilhada.

Para usar a interface do usuário para configurar um cluster para executar um script de inicialização, conclua as etapas a seguir:

  1. Na página de configuração do cluster, clique na alternância Opções Avançadas.
  2. Na parte inferior da página, clique na guia Scripts de Inicialização.
  3. Na lista suspensa Origem, selecione o tipo de origem Workspace, Volume ou ABFSS.
  4. Especifique um caminho para o script de inicialização, como um dos seguintes exemplos:
    • Para um script de inicialização armazenado em seu diretório inicial com arquivos de workspace: /Users/<user-name>/<script-name>.sh.
    • Para um script de inicialização armazenado com volumes do Catálogo do Unity: /Volumes/<catalog>/<schema>/<volume>/<path-to-script>/<script-name>.sh.
    • Para um script de inicialização armazenado com armazenamento de objetos: abfss://container-name@storage-account-name.dfs.core.windows.net/path/to/init-script.
  5. Clique em Adicionar.

No modo de acesso de usuário único, a identidade da entidade de segurança atribuída (um usuário ou entidade de serviço) é usada.

No modo de acesso compartilhado, a identidade do proprietário do cluster é usada.

Observação

O modo de acesso compartilhado sem isolamento não dá suporte a volumes, mas usa a mesma atribuição de identidade que o modo de acesso compartilhado.

Para remover um script da configuração de cluster, clique no ícone para excluir à direita do script. Ao confirmar a exclusão, você precisará reiniciar o cluster. Opcionalmente, você pode excluir o arquivo de script do local em que o carregou.

Observação

Se você configurar um script de inicialização usando o tipo de origem ABFSS, deverá configurar as credenciais de acesso.

O Databricks recomenda que você use as entidades de serviço do Microsoft Entra ID para gerenciar o acesso aos scripts de inicialização armazenados no Azure Data Lake Storage Gen2. Use a seguinte documentação vinculada para concluir esta configuração:

  1. Crie uma entidade de serviço com permissões de leitura e lista em seus blobs desejados. Consulte Acessar o armazenamento usando uma entidade de serviço e o Microsoft Entra ID (Azure Active Directory).

  2. Salve suas credenciais usando segredos. Confira Segredos.

  3. Defina as propriedades na configuração do Spark e variáveis ambientais ao criar um cluster, como no exemplo a seguir:

    Configuração do Spark:

    spark.hadoop.fs.azure.account.auth.type.<storage-account>.dfs.core.windows.net OAuth
spark.hadoop.fs.azure.account.oauth.provider.type.<storage-account>.dfs.core.windows.net org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider
spark.hadoop.fs.azure.account.oauth2.client.id.<storage-account>.dfs.core.windows.net <application-id>
spark.hadoop.fs.azure.account.oauth2.client.secret.<storage-account>.dfs.core.windows.net {{secrets/<secret-scope>/<service-credential-key>}}
spark.hadoop.fs.azure.account.oauth2.client.endpoint.<storage-account>.dfs.core.windows.net https://login.microsoftonline.com/<tenant-id>/oauth2/token

    Variáveis de ambiente:

    SERVICE_CREDENTIAL={{secrets/<secret-scope>/<service-credential-key>}}

  4. (Opcional) Refatorar scripts de inicialização usando azcopy ou a CLI do Azure.

    Você pode referenciar variáveis ambientais definidas durante a configuração do cluster em seus scripts de inicialização para passar credenciais armazenadas como segredos para validação.

Aviso

Os scripts de inicialização no escopo do cluster no DBFS atingiram o fim do ciclo de vida. A opção DBFS na interface do usuário em alguns workspaces existe para suportar cargas de trabalho herdadas e não é recomendada. Todos os scripts de inicialização armazenados no DBFS devem ser migrados. Para obter instruções de migração, consulte Migrar scripts de inicialização do DBFS.

Solução de problemas de scripts de inicialização com escopo de cluster

  • O script precisa existir no local configurado. Se o script não existir, as tentativas de iniciar o cluster ou escalar verticalmente os executores resultarão em falha.
  • O script de inicialização não pode ser maior que 64 KB. Se um script exceder esse tamanho, o cluster não será iniciado e uma mensagem de falha será exibida no log do cluster.