Migrar do dbx para os pacotes

Artigo
10/09/2024

Importante

O Databricks recomenda que você use os Pacotes de Ativos do Databricks em vez do dbx by Databricks Labs. Os artigos relacionados a dbx foram desativados e podem não estar atualizados.

Este artigo descreve como migrar projetos do dbx by Databricks Labs para os Pacotes de Ativos do Databricks. Confira Introdução ao dbx by Databricks Labs e O que são Pacotes de Ativos do Databricks?.

Antes de migrar, observe as limitações e as comparações de recursos a seguir entre o dbx by Databricks Labs e os Pacotes de Ativos do Databricks.

Limitações

A funcionalidade a seguir, com suporte no dbx by Databricks Labs é limitada, não existe ou exige soluções alternativas nos Pacotes de Ativos do Databricks.

Não há suporte à criação de artefatos JAR nos pacotes.
Não há suporte à notação FUSE em caminhos de workspace nos pacotes (por exemplo, /Workspace/<path>/<filename>). No entanto, você pode instruir os pacotes a gerar caminhos de workspace no estilo FUSE durante as implantações por meio de notação do tipo /Workspace/${bundle.file_path}/<filename>.

Comparações entre recursos

Antes de migrar, observe como os recursos do dbx by Databricks Labs a seguir são implementados nos Pacotes de Ativos do Databricks.

Modelos e projetos

dbx dá suporte à modelagem Jinja. Você pode incluir modelos Jinja na configuração de implantação e transmitir variáveis de ambiente em linha ou por meio de um arquivo de variáveis. Embora não seja recomendado, o dbx também dá suporte experimental a funções de usuário personalizadas.

Os pacotes dão suporte a modelos Go para reutilização de configuração. Os usuários podem criar pacotes com base em modelos predefinidos. Há uma paridade quase completa para modelagem, exceto em relação a funções de usuário personalizadas.

Gerenciamento do build

dbx dá suporte ao build por meio de pip wheel, Poetry e Flit. Os usuários podem especificar a opção de build na seção build do arquivo deployment.yml de um projeto.

Os pacotes permitem que os usuários criem, implantem e executem arquivos wheel do Python. Os usuários podem aproveitar a entrada interna whl no arquivo databricks.yml de um pacote.

Sincronizar, implantar e executar código

dbx permite o upload de código separadamente da geração de recursos de workspace, por exemplo, trabalhos do Azure Databricks.

Os pacotes sempre carregam código e criam ou atualizam recursos de workspace ao mesmo tempo. Isso simplifica as implantações e evita o bloqueio de condições em trabalhos que já estão em andamento.

Migrar um projeto dbx para um pacote

Depois de observar as limitações e as comparações de recursos acima entre o dbx by Databricks Labs e os Pacotes de Ativos do Databricks, você já estará pronto para fazer a migração do dbx para os pacotes.

O Databricks recomenda que, para iniciar uma migração de projeto dbx, você mantenha o projeto dbx na pasta original e tenha uma pasta separada em branco na qual copiará o conteúdo do projeto dbx original. Essa pasta separada será seu novo pacote. Você poderá encontrar problemas inesperados se começar a converter o projeto dbx na pasta original em um pacote e, em seguida, cometer alguns erros ou desejar começar do zero.

Etapa 1: instalar e configurar a CLI do Databricks

Os Databricks Asset Bundles estão geralmente disponíveis na CLI do Databricks versão 0.218.0 e superior. Se você já instalou e configurou a CLI do Databricks versão 0.218.0 ou superior, vá para a Etapa 2.

Observação

Os pacotes não são compatíveis com as versões 0.18 ou inferiores da CLI do Databricks.

Instale ou atualize para a CLI do Databricks versão 0.218.0 ou superior. Consulte Instalar ou atualizar a CLI do Databricks.
Configure a CLI do Databricks para autenticação com seus workspaces do Azure Databricks de destino, por exemplo, usando a autenticação com token de acesso pessoal do Azure Databricks. Para outros tipos de autenticação do Azure Databricks, consulte Autenticação para a CLI do Databricks.

Etapa 2: Criar o arquivo de configuração do pacote

Se você estiver usando um IDE, como o Visual Studio Code, PyCharm Professional ou IntelliJ IDEA Ultimate que fornece suporte para arquivos YAML e arquivos de esquema JSON, você pode usar o IDE não apenas para criar o arquivo de configuração do pacote, mas para verificar a sintaxe e a formatação do arquivo e fornecer dicas de conclusão de código da seguinte maneira.

Visual Studio Code

Adicione suporte ao servidor de linguagem 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 Pacote de Ativos do Databricks usando a CLI do Databricks para executar o comando bundle schema 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
```
Use o Visual Studio Code para criar ou abrir um arquivo de configuração de pacote no diretório atual. Por convenção, esse arquivo é nomeado databricks.yml.
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.
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

Gere o arquivo de esquema JSON de configuração do Pacote de Ativos do Databricks usando a CLI do Databricks para executar o comando bundle schema 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
```
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.
Use o PyCharm para criar ou abrir um arquivo de configuração de pacote. Por convenção, esse arquivo é 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

Gere o arquivo de esquema JSON de configuração do Pacote de Ativos do Databricks usando a CLI do Databricks para executar o comando bundle schema 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
```
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.
Use o IntelliJ IDEA para criar ou abrir um arquivo de configuração de pacote. Por convenção, esse arquivo é 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 3: converter configurações de projeto dbx em databricks.yml

Converta as configurações no arquivo .dbx/project.json do projeto dbx nas configurações equivalentes no arquivo databricks.yml do pacote. Para obter detalhes, consulte Converter as configurações do projeto dbx em databricks.yml.

Etapa 4: converter configurações de implantação dbx em databricks.yml

Converta as configurações da pasta conf do projeto dbx nas configurações equivalentes do arquivo databricks.yml do pacote. Para obter detalhes, consulte Converter as configurações de implantação dbx em databricks.yml.

Etapa 5: validar o pacote

Antes de implantar artefatos ou executar um trabalho do Azure Databricks, um pipeline do Delta Live Tables ou um pipeline do MLOps, verifique se o arquivo de configurações do pacote está sintaticamente correto. Para isso, execute o comando bundle validate na raiz do pacote:

databricks bundle validate

Para obter informações sobre bundle validate, veja Validar um pacote configurável.

Etapa 6: implantar o pacote

Para implantar artefatos locais especificados (se for o caso) no workspace remoto, execute o comando bundle deploy na raiz do pacote. Se nenhuma opção de comando for especificada, será usado o destino padrão declarado no arquivo de configuração do pacote:

databricks bundle deploy

Para implantar os artefatos no contexto de um destino específico, especifique a opção -t (ou --target) junto com o nome do destino, conforme declarado no arquivo de configuração do pacote. Por exemplo, para um destino declarado com o nome development:

databricks bundle deploy -t development

Para obter informações sobre bundle deploy, veja Implantar um pacote configurável.

Dica

Você pode vincular trabalhos e pipelines definidos por pacote a trabalhos e pipelines existentes no espaço de trabalho do Azure Databricks para mantê-los sincronizados. Veja Vincular recursos de pacote.

Etapa 7: executar o pacote

Para executar um trabalho ou pipeline específico, execute o comando bundle run na raiz do pacote. Você deve especificar o trabalho ou o pipeline declarado no arquivo de configuração do pacote. Se a opção -t não for especificada, será usado o destino padrão, conforme declarado no arquivo de configuração do pacote. Por exemplo, para executar um trabalho chamado hello_job dentro do contexto do destino padrão:

databricks bundle run hello_job

Para executar um trabalho chamado hello_job dentro do contexto de um destino declarado com o nome development:

databricks bundle run -t development hello_job

Para obter informações sobre bundle runo , consulte Executar um trabalho ou pipeline.

(Opcional) Etapa 8: configurar o pacote para CI/CD com o GitHub

Se você usar o GitHub para CI/CD, poderá usar o GitHub Actions para executar os comandos databricks bundle deploy e databricks bundle run automaticamente com base em eventos específicos do fluxo de trabalho do GitHub e em outros critérios. Confira Executar um fluxo de trabalho de CI/CD com um Pacote de Ativos do Databricks e o GitHub Actions.

Convertendo configurações de projeto dbx em databricks.yml

Para o dbx, as configurações de projeto ficam, por padrão, em um arquivo chamado project.json na pasta .dbx do projeto. Consulte a Referência do arquivo de projeto.

Para pacotes, as configurações de pacote estão, por padrão, em um arquivo nomeado databricks.yml dentro da pasta raiz do pacote. Confira Configuração do Pacote de Ativos do Databricks.

Para um arquivo conf/project.json com o seguinte conteúdo de exemplo:

{
  "environments": {
    "default": {
      "profile": "charming-aurora",
      "storage_type": "mlflow",
      "properties": {
        "workspace_directory": "/Workspace/Shared/dbx/charming_aurora",
        "artifact_location": "/Workspace/Shared/dbx/projects/charming_aurora"
      }
    }
  },
  "inplace_jinja_support": true
}

O arquivo databricks.yml correspondente é o seguinte:

bundle:
  name: <some-unique-bundle-name>

targets:
  default:
    workspace:
      profile: charming-aurora
      root_path: /Shared/dbx/charming_aurora
      artifact_path: /Shared/dbx/projects/charming_aurora
    resources:
      # See an example "resources" mapping in the following section.

Os seguintes objetos no arquivo conf/project.json anterior do exemplo não são compatíveis com arquivos databricks.yml e não existem soluções alternativas:

inplace_jinja_support
storage_type

Os seguintes objetos permitidos adicionais nos arquivos conf/project.json não são compatíveis com arquivos databricks.yml e não existem soluções alternativas:

enable-context-based-upload-for-execute
enable-failsafe-cluster-reuse-with-assets

Convertendo configurações de implantação dbx em databricks.yml

No caso do dbx, as configurações de implantação ficam, por padrão, em um arquivo dentro da pasta conf do projeto. Consulte a Referência do arquivo de implantação. O arquivo de configurações de implantação têm, por padrão, um dos seguintes nomes de arquivo:

deployment.yml
deployment.yaml
deployment.json
deployment.yml.j2
deployment.yaml.j2
deployment.json.j2

No caso dos pacotes, as configurações de implantação ficam, por padrão, em um arquivo chamado databricks.yml dentro da pasta raiz do pacote. Confira Configuração do Pacote de Ativos do Databricks.

Para um arquivo conf/deployment.yml com o seguinte conteúdo de exemplo:

build:
  python: "pip"

environments:
  default:
    workflows:
      - name: "workflow1"
        tasks:
          - task_key: "task1"
            python_wheel_task:
              package_name: "some-pkg"
              entry_point: "some-ep"