Migrar de dbx para bundles

Este artigo descreve como migrar projetos da dbx Databricks Labs para Pacotes de Automação Declarativa. Veja Introdução ao dbx pela Databricks Labs e O que são os Pacotes de Automação Declarativa?.

Antes de migrar, note as seguintes limitações e comparações de funcionalidades entre dbx o Databricks Labs e os Declarative Automation Bundles.

Comparações de recursos

Antes de migrar, note como as seguintes funcionalidades do "dbx" pelos Databricks Labs são implementadas em Pacotes de Automação Declarativa.

Modelos e projetos

dbx fornecer suporte para Jinja templating. 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á quase paridade total nos templates, exceto para funções de utilizador personalizadas.

Gestão de edifícios

dbx fornece suporte à compilação através de pip wheel, Poetry 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 utilizadores podem aproveitar a entrada interna whl no arquivo databricks.yml de 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 Lakeflow Jobs.

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 e comparações de funcionalidades entre dbx por Databricks Labs e Declarative Automation Bundles, está pronto para migrar de dbx para bundles.

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 Automação Declarativa estão geralmente disponíveis na versão 0.218.0 da CLI Databricks e superiores. Se você já tiver instalado e configurado a CLI do Databricks versão 0.218.0 ou superior, pule para a Etapa 2.

1. Instale ou atualize para a CLI do Databricks versão 0.218.0 ou superior. Consulte Instalar ou atualizar a CLI do Databricks.
2. Configure o Databricks CLI para a autenticação com os seus espaços de trabalho de destino no Azure Databricks, por exemplo, usando a autenticação por token de acesso pessoal (obsoleta). 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.

Código do Visual Studio

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

2. Gerar o ficheiro de esquema JSON da configuração do bundle utilizando o Databricks CLI para executar o comando bundle schema e redirecionar a saída para um ficheiro JSON. Por exemplo, gere um arquivo chamado bundle_config_schema.json dentro do 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 dentro do diretório atual. Por convenção, este ficheiro é chamado databricks.yml.

4. 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 ficheiro de esquema JSON da configuração do bundle estiver num caminho diferente, substitua bundle_config_schema.json pelo caminho completo para o ficheiro de esquema.

5. 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

1. Gera o ficheiro de esquema JSON de configuração do bundle através da CLI Databricks, execute o comando bundle schema e redirecione a saída para um ficheiro JSON. Por exemplo, gere um arquivo chamado bundle_config_schema.json dentro do 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 do pacote e, em seguida, conclua o mapeamento do 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. Por convenção, este ficheiro é chamado 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

1. Gerar o ficheiro JSON de esquema do bundle de configuração utilizando a CLI Databricks para executar o comando bundle schema e redirecionar a saída para um ficheiro JSON. Por exemplo, gere um arquivo chamado bundle_config_schema.json dentro do 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 do pacote e, em seguida, conclua o mapeamento do 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. Por convenção, este ficheiro é chamado databricks.yml. À medida que digitas, o IntelliJ IDEA verifica a sintaxe e a formatação do esquema JSON e fornece sugestões de preenchimento automático de código.

Etapa 3: Converter as configurações do projeto dbx em databricks.yml

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

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

Converta as configurações na pasta do dbx seu conf projeto para as configurações equivalentes no arquivo do databricks.yml seu pacote. Para obter detalhes, consulte Convertendo 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 :, ou um pipeline MLOps, você deve certificar-se de que seu 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 validate, consulte databricks bundle validate.

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 deploy, consulte databricks bundle deploy.

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, consulte bundle run sobre .

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

Se utilizar o GitHub para CI/CD, pode utilizar GitHub Actions para executar automaticamente os comandos databricks bundle deploy e databricks bundle run, com base em eventos específicos do fluxo de trabalho do GitHub e noutros critérios. Consulte 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 chamado databricks.yml dentro da pasta raiz do bundle. Ver configuração dos Pacotes de Automação Declarativa.

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. Ver configuração dos Pacotes de Automação Declarativa.

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'

O ficheiro correspondente databricks.yml é o seguinte:

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

targets:
  default:
    workspace:
      # See an example "workspace" mapping in the preceding section.
    resources:
      jobs:
        workflow1:
          tasks:
            - task_key: task1
              python_wheel_task:
                package_name: some-pkg
                entry_point: some-ep

O seguinte objeto no arquivo anterior conf/deployment.yml deste exemplo não é suportado em databricks.yml arquivos e não tem soluções alternativas:

• build (embora veja Construir um ficheiro de volante em Python usando Pacotes de Automação Declarativa)

Os seguintes objetos adicionais permitidos e funcionalidade em conf/deployment.yml arquivos não são suportados em databricks.yml arquivos e não têm soluções alternativas, a menos que indicado de outra forma:

• access_control_list
• custom (use âncoras YAML padrão em vez disso)
• deployment_config
• Formato Lakeflow Jobs 2.0 (utilize em vez disso o formato Jobs 2.1)
• dbx Jinja características
• Propriedades baseadas em nome