Desenvolvimento dos Pacotes de Ativos do Databricks

Este artigo descreve o desenvolvimento e o ciclo de vida de um Pacote de Ativos do Databricks. Para saber mais sobre os Pacotes de Ativos do Databricks, confira O que são os Pacotes de Ativos do Databricks?.

Ciclo de vida de um pacote

Para entender como usar pacotes ​​de maneira eficaz, é importante entender o ciclo de vida básico de um pacote:

1. A estrutura do pacote é criada com base em um projeto.
2. O projeto do pacote é desenvolvido localmente. Um pacote contém arquivos de configuração que definem as configurações da infraestrutura e do workspace, como destinos de implantação, configurações para recursos do Databricks como trabalhos e pipelines, arquivos de origem e outros artefatos.
3. 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 ele seja implantável no Databricks.
4. O pacote é implantado em um workspace de destino. Em geral, um pacote é implantado primeiro no workspace de desenvolvimento pessoal de um usuário para teste. Depois que o teste do pacote é concluído, ele pode ser implantado no ambiente de preparo e, em seguida, nos destinos de produção.
5. Os recursos de fluxo de trabalho definidos no pacote implantado podem ser executados. Por exemplo, é possível executar um trabalho.
6. Se o pacote não estiver mais sendo usado, ele poderá 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:

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

Use um modelo de pacote padrão

Para usar um modelo de pacote padrão do Azure Databricks a fim de criar um pacote inicial que possa ser personalizado, use a CLI do Databricks versão 0.218.0 ou versões posteriores para executar o comando bundle init, que permite escolher entre uma lista de modelos disponíveis. Confira Criar um pacote com base em um modelo de projeto.

databricks bundle init

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

Vá para Etapa 2: preencher os arquivos de configuração do pacote.

Use um modelo de pacote personalizado

Para utilizar um modelo de pacote diferente do modelo de pacote padrão do Azure Databricks, você deve conhecer 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 versões posteriores para executar o comando bundle init da seguinte maneira:

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

Para obter mais informações sobre esse comando, confira os modelos do projeto de Pacote de Ativos do Databricks. Para obter informações sobre um modelo de pacote específico, consulte a documentação do provedor de modelo de pacote.

Vá para Etapa 2: preencher os arquivos de configuração do pacote.

Criar um pacote manualmente

Para criar um pacote configurável manualmente em vez de usar um modelo de pacote configurável, 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 configurável como entrada. Esses arquivos são expressos no formato YAML. Deve haver, no mínimo, um (e apenas um) arquivo de configuração de pacote chamado databricks.yml. Arquivos de configuração de pacote configurável adicionais devem ser referenciados no include mapeamento do arquivo databricks.yml.

Para criar arquivos YAML com mais facilidade e rapidez que estejam em conformidade com a sintaxe de configuração do Pacote de Ativos do Databricks, use uma ferramenta como o Visual Studio Code, o PyCharm Professional ou o IntelliJ IDEA Ultimate que forneça suporte para arquivos YAML e arquivos de esquema JSON, da seguinte maneira:

Visual Studio Code

1. Adicione suporte ao servidor de linguagem YAML ao Visual Studio Code, por exemplo, instalando a extensão YAML do Visual Studio Code Marketplace.

2. Gere o arquivo de esquema JSON de configuração do Pacote de Ativos do Databricks usando a CLI do Databricks versão 0.218.0 ou versões posteriores para executar o bundle schema comando e redirecionar a saída para um arquivo JSON. Por exemplo, gere um arquivo chamado bundle_config_schema.json no diretório atual, da seguinte maneira:

   databricks bundle schema > bundle_config_schema.json
   

3. Use o Visual Studio Code para criar ou abrir um arquivo de configuração de pacote no diretório atual. Esse arquivo deve ser nomeado databricks.yml.

4. Adicione o seguinte comentário ao início do arquivo de configurações do pacote:

   # yaml-language-server: $schema=bundle_config_schema.json
   

   Observação

   No comentário anterior, se o arquivo de esquema JSON das configurações do Pacote de Ativos do Databricks estiver em um caminho diferente, substitua bundle_config_schema.json pelo caminho completo do arquivo de esquema.

5. Use os recursos do servidor de linguagem YAML adicionados anteriormente. Para obter mais informações, consulte a documentação do servidor de linguagem YAML.

PyCharm Professional

1. Gere o arquivo de esquema JSON de configuração do Pacote de Ativos do Databricks usando a CLI do Databricks versão 0.218.0 ou versões posteriores para executar o bundle schema comando e redirecionar a saída para um arquivo JSON. Por exemplo, gere um arquivo chamado bundle_config_schema.json no diretório atual, da seguinte maneira:

   databricks bundle schema > bundle_config_schema.json
   

2. Configure o PyCharm para reconhecer o arquivo de esquema JSON de configuração de pacote e conclua o mapeamento de esquema JSON seguindo as instruções em Configurar um esquema JSON personalizado.

3. Use o PyCharm para criar ou abrir um arquivo de configuração de pacote. Esse arquivo deve ser nomeado databricks.yml. Conforme 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

1. Gere o arquivo de esquema JSON de configuração do Pacote de Ativos do Databricks usando a CLI do Databricks versão 0.218.0 ou versões posteriores para executar o bundle schema comando e redirecionar a saída para um arquivo JSON. Por exemplo, gere um arquivo chamado bundle_config_schema.json no diretório atual, da seguinte maneira:

   databricks bundle schema > bundle_config_schema.json
   

2. Configure o IntelliJ IDEA para reconhecer o arquivo de esquema JSON de configuração de pacote e conclua o mapeamento de esquema JSON seguindo as instruções em Configurar um esquema JSON personalizado.

3. Use o IntelliJ IDEA para criar ou abrir um arquivo de configuração de pacote. Esse arquivo deve ser nomeado databricks.yml. Conforme você digita, o IntelliJ IDEA verifica a sintaxe e a formatação do esquema JSON e fornece dicas de conclusão de código.

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

Os arquivos de configuração do pacote definem os fluxos de trabalho do Azure Databricks especificando configurações como detalhes do workspace, nomes de artefatos, localizações de arquivos, detalhes de trabalhos e detalhes de pipelines. Em geral, a configuração do pacote também contém destinos de implantação de desenvolvimento, preparo e produção. Para obter informações detalhadas sobre arquivos de configuração do pacote, consulte as Configurações do Pacote de Ativos do Databricks.

É possível usar o comando bundle generate para gerar automaticamente a configuração do pacote para um recurso atual no workspace e, em seguida, usar bundle deployment bind para vincular a configuração do pacote ao recurso no workspace e mantê-los sincronizados. Consulte Gerar um arquivo de configuração de pacote e Associar recursos do pacote.

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

Antes de implantar artefatos ou executar um trabalho ou pipeline, verifique se as definições nos arquivos de configuração do pacote são válidas. Para isso, execute o comando bundle validate no diretório raiz do projeto do pacote. Confira 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 o esquema, use o comando databricks bundle schema. Confira Exibir o esquema de configuração do pacote.

Etapa 4: implantar o pacote

Antes de implantar o pacote, verifique se o workspace remoto tem arquivos de workspace habilitados. Consulte O que são Arquivos de workspace?.

Para implantar um pacote em um workspace remoto, execute o comando bundle deploy na raiz do pacote, conforme descrito em Implantar um pacote. A CLI do Databricks é implantada no workspace de destino declarado nos arquivos de configuração do pacote. Confira destinos.

databricks bundle deploy

A identidade exclusiva de um pacote é definida pelo nome e destino dele e pela identidade do implantador. Quando esses atributos são idênticos em diferentes pacotes, a implantação dos pacotes sofre interferência. Confira Implantar um pacote para saber mais.

Etapa 5: executar o pacote

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

databricks bundle run hello_job

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

databricks bundle run -t dev hello_job

Etapa 6: destruir o pacote

Depois de concluir o pacote, se você deseja excluir os trabalhos, pipelines e artefatos implantados anteriormente, deve executar o comando bundle destroy na raiz dele. Este comando exclui todos os trabalhos, pipelines e artefatos implantados anteriormente que estão definidos nos arquivos de configuração do pacote. Confira Implantar um pacote.

databricks bundle destroy

Por padrão, você receberá uma solicitação para 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 opção --auto-approve ao comando bundle destroy.