Migrar de dbx para bundles

Artigo
10/09/2024

Importante

O Databricks recomenda que você use o Databricks Asset Bundles em vez do dbx Databricks Labs. Artigos relacionados sobre dbx foram retirados e podem não ser atualizados.

Este artigo descreve como migrar projetos do dbx Databricks Labs para o Databricks Asset Bundles. Consulte Introdução ao dbx pelo Databricks Labs e O que são Databricks Asset Bundles?.

Antes de migrar, observe as seguintes limitações e comparações de recursos entre dbx o Databricks Labs e o Databricks Asset Bundles.

Limitações

A funcionalidade a seguir suportada dbx pelo Databricks Labs é limitada, não existe ou requer soluções alternativas no Databricks Asset Bundles.

A criação de artefatos JAR não é suportada em pacotes.
A notação FUSE para caminhos de espaço de trabalho não é suportada em pacotes (por exemplo, /Workspace/<path>/<filename>). No entanto, você pode instruir pacotes a gerar caminhos de espaço de trabalho no estilo FUSE durante implantações usando notações como /Workspace/${bundle.file_path}/<filename>.

Comparações de recursos

Antes de migrar, observe como os seguintes recursos do dbx Databricks Labs são implementados no Databricks Asset Bundles.

Modelos e projetos

dbx fornecer suporte para modelos Jinja. Você pode incluir modelos Jinja na configuração de implantação e passar variáveis de ambiente em linha ou através de um arquivo de variáveis. Embora não seja recomendado, dbx também fornece suporte experimental para funções de usuário personalizadas.

Os pacotes fornecem suporte para modelos Go para reutilização de configuração. Os usuários podem criar pacotes com base em modelos pré-construídos. Há paridade quase total para modelos, exceto para funções de usuário personalizadas.

Gestão de edifícios

dbx fornece apoio à construção através de pip wheel, Poesia e Flit. Os usuários podem especificar a opção de compilação na build seção do arquivo de um projeto deployment.yml .

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

Sincronize, implante e execute código

dbx permite carregar código separadamente da geração de recursos do espaço de trabalho, como trabalhos do Azure Databricks.

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

Migrar um projeto dbx para um pacote

Depois de observar as limitações anteriores e as comparações de recursos entre dbx o Databricks Labs e o Databricks Asset Bundles, você estará pronto para migrar de dbx para pacotes.

O Databricks recomenda que, para iniciar uma dbx migração de projeto, você mantenha seu dbx projeto em sua pasta original e tenha uma pasta separada e em branco para a qual copie o conteúdo do projeto original dbx . Esta pasta separada será o seu novo pacote. Você pode encontrar problemas inesperados se você começar a converter seu dbx projeto em sua pasta original para um pacote e, em seguida, cometer alguns erros ou quiser começar de novo desde o início,

Etapa 1: Instalar e configurar a CLI do Databricks

Os pacotes de ativos Databricks estão geralmente disponíveis na CLI do Databricks versão 0.218.0 e superior. Se você já tiver instalado e configurado a CLI do Databricks versão 0.218.0 ou superior, pule para a Etapa 2.

Nota

Os pacotes não são compatíveis com as versões 0.18 e 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 espaços de trabalho de destino do Azure Databricks, por exemplo, usando a autenticação de 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 Visual Studio Code, PyCharm Professional ou IntelliJ IDEA Ultimate que fornece suporte para arquivos YAML e arquivos de esquema JSON, você pode usar seu 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 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 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. Por convenção, esse arquivo é chamado databricks.ymlde .
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 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. Por convenção, esse arquivo é chamado databricks.ymlde . À 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 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. Por convenção, esse arquivo é chamado databricks.ymlde . À 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 3: Converter as configurações do projeto dbx em databricks.yml

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

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

Converta as configurações na pasta do conf seu dbx projeto para as configurações equivalentes no arquivo do databricks.yml seu pacote. Para obter detalhes, consulte Convertendo configurações de implantação dbx para databricks.yml.

Etapa 5: Validar o pacote

Antes de implantar artefatos ou executar um trabalho do Azure Databricks, um pipeline Delta Live Tables ou um pipeline MLOps, você deve certificar-se de que o arquivo de configuração do pacote está sintaticamente correto. Para fazer isso, execute o bundle validate comando a partir da raiz do pacote:

databricks bundle validate

Para obter informações sobre bundle validateo , consulte Validar um pacote.

Etapa 6: Implantar o pacote

Para implantar quaisquer artefatos locais especificados no espaço de trabalho remoto, execute o bundle deploy comando a partir da raiz do pacote. Se nenhuma opção de comando for especificada, o destino padrão declarado no arquivo de configuração do pacote será usado:

databricks bundle deploy

Para implantar os artefatos no contexto de um destino específico, especifique a -t opção (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 deployo , consulte Implantar um pacote.

Gorjeta

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

Etapa 7: Executar o pacote

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

databricks bundle run hello_job

Para executar um trabalho nomeado 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 as Ações do GitHub para executar os comandos e databricks bundle run automaticamente, com base em eventos específicos do fluxo de trabalho do databricks bundle deploy GitHub e outros critérios. Consulte Executar um fluxo de trabalho de CI/CD com um pacote de ativos Databricks e ações do GitHub.

Convertendo as configurações do projeto dbx em databricks.yml

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

Para bundles, as configurações de bundle são, por padrão, em um arquivo nomeado databricks.yml dentro da pasta raiz do bundle. Consulte Configuração do Databricks Asset Bundle.

Para um conf/project.json arquivo 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 ficheiro correspondente databricks.yml é 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 anterior conf/project.json deste exemplo não são suportados em databricks.yml arquivos e não têm soluções alternativas:

inplace_jinja_support
storage_type

Os seguintes objetos adicionais permitidos em conf/project.json arquivos não são suportados em databricks.yml arquivos e não têm soluções alternativas:

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

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

Para dbx, as configurações de implantação são, por padrão, em um arquivo dentro da pasta do conf projeto. Consulte Referência do arquivo de implantação. O arquivo de configurações de implantação por padrão tem um dos seguintes nomes de arquivo:

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

Para pacotes, as configurações de implantação são, por padrão, em um arquivo nomeado databricks.yml dentro da pasta raiz do pacote. Consulte Configuração do Databricks Asset Bundle.

Para um conf/deployment.yml arquivo 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"