Desenvolvimento de Databricks Asset Bundles

Artigo
06/14/2024

Este artigo descreve o desenvolvimento e o ciclo de vida de um Databricks Asset Bundle. Para obter informações gerais sobre Databricks Asset Bundles, consulte O que são Databricks Asset Bundles?.

Ciclo de vida de um pacote

Para entender como usar pacotes de forma eficaz, você precisa entender o ciclo de vida básico de um pacote:

O esqueleto do pacote é criado com base em um projeto.
O projeto do pacote é desenvolvido localmente. Um pacote contém arquivos de configuração que definem configurações de infraestrutura e espaço de trabalho, como destinos de implantação, configurações para recursos do Databricks, como trabalhos e pipelines, bem como arquivos de origem e outros artefatos.
O projeto do pacote é validado. A validação verifica as configurações e definições de recursos na configuração do pacote em relação aos esquemas de objeto correspondentes para garantir que o pacote possa ser implantado no Databricks.
O pacote é implantado em um espaço de trabalho de destino. Mais comumente, um pacote é implantado primeiro no espaço de trabalho de desenvolvimento pessoal de um usuário para teste. Uma vez concluído o teste do pacote, o pacote pode ser implantado no preparo e, em seguida, nos destinos de produção.
Os recursos de fluxo de trabalho definidos no pacote implantado podem ser executados. Por exemplo, você pode executar um trabalho.
Se o pacote não estiver mais sendo usado, ele pode ser destruído permanentemente.

Use os comandos de pacote da CLI do Databricks para criar, validar, implantar, executar e destruir pacotes, conforme descrito nas seções a seguir.

Etapa 1: Criar um pacote

Há três maneiras de começar a criar um pacote:

Use o modelo de pacote padrão.
Use um modelo de pacote personalizado.
Crie um pacote manualmente.

Usar um modelo de pacote padrão

Para usar um modelo de pacote padrão do Azure Databricks para criar um pacote inicial que você pode personalizar ainda mais, use a CLI do Databricks versão 0.218.0 ou superior para executar o bundle init comando, que permite escolher em uma lista de modelos disponíveis. Consulte Criar um pacote a partir de um modelo de projeto.

databricks bundle init

Você pode visualizar a origem dos modelos de pacote padrão nos repositórios públicos do Github databricks/cli e databricks/mlops-stacks.

Pule para a Etapa 2: preencher os arquivos de configuração do pacote.

Usar um modelo de pacote personalizado

Para usar um modelo de pacote diferente do modelo de pacote padrão do Azure Databricks, você deve saber o caminho local ou a URL para o local do modelo de pacote remoto. Use a CLI do Databricks versão 0.218.0 ou superior para executar o bundle init comando da seguinte maneira:

databricks bundle init <project-template-local-path-or-url>

Para obter mais informações sobre esse comando, consulte Modelos do Databricks Asset Bundle. Para obter informações sobre um modelo de pacote específico, consulte a documentação do provedor de modelo de pacote.

Pule para a Etapa 2: preencher os arquivos de configuração do pacote.

Criar um pacote manualmente

Para criar um pacote manualmente em vez de usar um modelo de pacote, crie um diretório de projeto em sua máquina local ou um repositório vazio com um provedor Git de terceiros.

Em seu diretório ou repositório, crie um ou mais arquivos de configuração de pacote como entrada. Esses arquivos são expressos em formato YAML. Deve haver pelo menos um (e apenas um) arquivo de configuração de pacote chamado databricks.yml. Arquivos de configuração de pacote adicionais devem ser referenciados no include mapeamento do databricks.yml arquivo.

Para criar arquivos YAML de forma mais fácil e rápida que estejam em conformidade com a sintaxe de configuração do Databricks Asset Bundle, você pode usar uma ferramenta como Visual Studio Code, PyCharm Professional ou IntelliJ IDEA Ultimate que fornece suporte para arquivos YAML e arquivos de esquema JSON, da seguinte maneira:

Visual Studio Code

Adicione suporte ao servidor de idiomas YAML ao Visual Studio Code, por exemplo, instalando a extensão YAML do Visual Studio Code Marketplace.
Gere o arquivo de esquema JSON de configuração do Databricks Asset Bundle usando a CLI do Databricks versão 0.218.0 ou superior para executar o bundle schema comando e redirecionar a saída para um arquivo JSON. Por exemplo, gere um arquivo nomeado bundle_config_schema.json dentro do diretório atual, da seguinte maneira:
```
databricks bundle schema > bundle_config_schema.json
```
Use o Visual Studio Code para criar ou abrir um arquivo de configuração de pacote dentro do diretório atual. Este arquivo deve ser nomeado databricks.yml.
Adicione o seguinte comentário ao início do arquivo de configuração do pacote:
```
# yaml-language-server: $schema=bundle_config_schema.json
```
Nota

No comentário anterior, se o arquivo de esquema JSON de configuração do Databricks Asset Bundle estiver em um caminho diferente, substitua bundle_config_schema.json pelo caminho completo para o arquivo de esquema.
Use os recursos do servidor de idiomas YAML que você adicionou anteriormente. Para obter mais informações, consulte a documentação do servidor de idiomas YAML.

PyCharm Profissional

Gere o arquivo de esquema JSON de configuração do Databricks Asset Bundle usando a CLI do Databricks versão 0.218.0 ou superior para executar o bundle schema comando e redirecionar a saída para um arquivo JSON. Por exemplo, gere um arquivo nomeado bundle_config_schema.json dentro do diretório atual, da seguinte maneira:
```
databricks bundle schema > bundle_config_schema.json
```
Configure o PyCharm para reconhecer o arquivo de esquema JSON de configuração do pacote e, em seguida, conclua o mapeamento do esquema JSON, seguindo as instruções em Configurar um esquema JSON personalizado.
Use o PyCharm para criar ou abrir um arquivo de configuração de pacote. Este arquivo deve ser nomeado databricks.yml. À medida que você digita, o PyCharm verifica a sintaxe e a formatação do esquema JSON e fornece dicas de conclusão de código.

IntelliJ IDEA Ultimate

Gere o arquivo de esquema JSON de configuração do Databricks Asset Bundle usando a CLI do Databricks versão 0.218.0 ou superior para executar o bundle schema comando e redirecionar a saída para um arquivo JSON. Por exemplo, gere um arquivo nomeado bundle_config_schema.json dentro do diretório atual, da seguinte maneira:
```
databricks bundle schema > bundle_config_schema.json
```
Configure o IntelliJ IDEA para reconhecer o arquivo de esquema JSON de configuração do pacote e, em seguida, conclua o mapeamento do esquema JSON, seguindo as instruções em Configurar um esquema JSON personalizado.
Use o IntelliJ IDEA para criar ou abrir um arquivo de configuração de pacote. Este arquivo deve ser nomeado databricks.yml. À medida que você digita, o IntelliJ IDEA verifica a sintaxe e a formatação do esquema JSON e fornece dicas de autocompletar código.

Etapa 2: preencher os arquivos de configuração do pacote

Os arquivos de configuração do pacote definem seus fluxos de trabalho do Azure Databricks especificando configurações como detalhes do espaço de trabalho, nomes de artefatos, locais de arquivos, detalhes do trabalho e detalhes do pipeline. Normalmente, a configuração do pacote também contém destinos de desenvolvimento, preparação e implantação de produção. Para obter informações detalhadas sobre arquivos de configuração de pacote, consulte Configurações do Databricks Asset Bundle.

Você pode usar o comando para gerar automaticamente a bundle generate configuração do pacote para um recurso existente no espaço de trabalho e, em seguida, usar bundle deployment bind para vincular a configuração do pacote ao recurso no espaço de trabalho para mantê-los sincronizados. Consulte Gerar um arquivo de configuração de pacote e Vincular recursos de pacote.

Etapa 3: Validar os arquivos de configuração do pacote

Antes de implantar artefatos ou executar um trabalho ou pipeline, você deve verificar se as definições em seus arquivos de configuração de pacote são válidas. Para fazer isso, execute o bundle validate comando a partir do diretório raiz do projeto bundle. Consulte Validar um pacote.

databricks bundle validate

Se a validação for bem-sucedida, um resumo da identidade do pacote e uma mensagem de confirmação serão retornados. Para gerar a saída do esquema, use o databricks bundle schema comando. Consulte Exibir o esquema de configuração do pacote.

Etapa 4: Implantar o pacote

Antes de implantar o pacote, verifique se o espaço de trabalho remoto tem os arquivos do espaço de trabalho habilitados. Consulte O que são arquivos de espaço de trabalho?.

Para implantar um pacote em um espaço de trabalho remoto, execute o bundle deploy comando a partir da raiz do pacote, conforme descrito em Implantar um pacote. A CLI do Databricks é implantada no espaço de trabalho de destino declarado nos arquivos de configuração do pacote. Veja as metas.

databricks bundle deploy

A identidade exclusiva de um pacote é definida por seu nome, destino e identidade do implantador. Se esses atributos forem idênticos em pacotes diferentes, a implantação desses pacotes interferirá uns com os outros. Consulte Implantar um pacote para obter detalhes adicionais.

Gorjeta

Você pode executar databricks bundle comandos fora da raiz do bundle definindo a BUNDLE_ROOT variável de ambiente. Se essa variável de ambiente não estiver definida, databricks bundle os comandos tentarão encontrar a raiz do bundle pesquisando dentro do diretório de trabalho atual.

Etapa 5: Executar o pacote

Para executar um trabalho ou pipeline específico, execute o bundle run comando a partir da raiz do pacote, especificando o trabalho ou a chave do pipeline declarada nos arquivos de configuração do pacote, conforme descrito em Executar um pacote. A chave de recurso é o elemento de nível superior do bloco YAML do recurso. Se você não especificar uma chave de trabalho ou pipeline, será solicitado que selecione um recurso a ser executado a partir de uma lista de recursos disponíveis. Se a -t opção não for especificada, o destino padrão conforme declarado nos arquivos de configuração do pacote será usado. Por exemplo, para executar um trabalho com a chave hello_job dentro do contexto do destino padrão:

databricks bundle run hello_job

Para executar um trabalho com uma chave hello_job dentro do contexto de um destino declarado com o nome dev:

databricks bundle run -t dev hello_job

Passo 6: Destrua o pacote

Se você tiver terminado o pacote e quiser excluir trabalhos, pipelines e artefatos que foram implantados anteriormente, execute o bundle destroy comando a partir da raiz do pacote. Este comando exclui todos os trabalhos, pipelines e artefatos implantados anteriormente que são definidos nos arquivos de configuração do pacote. Consulte Destruir um pacote.

databricks bundle destroy

Por padrão, você será solicitado a confirmar a exclusão permanente dos trabalhos, pipelines e artefatos implantados anteriormente. Para ignorar esses prompts e executar a exclusão permanente automática, adicione a --auto-approve opção ao bundle destroy comando.

Partilhar via