Use os utilitários UCX para atualizar seu workspace para o Catálogo do Unity

Este artigo apresenta o UCX, um projeto do Databricks Labs que fornece ferramentas para lhe ajudar a atualizar seu workspace não baseado no Catálogo do Unity para o Catálogo do Unity.

O projeto UCX fornece as seguintes ferramentas de migração e fluxos de trabalho:

1. Fluxo de trabalho de avaliação para lhe ajudar a planejar a migração.
2. Fluxo de trabalho de migração de grupos para lhe ajudar a atualizar a associação de grupos do seu workspace para a sua conta do Databricks e migrar as permissões para os novos grupos no nível da conta.
3. Fluxo de trabalho de migração de tabela para ajudá-lo a atualizar tabelas registradas no metastore do Hive do workspace para o metastore do Catálogo do Unity. Esse fluxo de trabalho também ajudará você a migrar locais de armazenamento e as credenciais necessárias para acessá-los.

Este diagrama mostra o fluxo geral de migração, identificando os fluxos de trabalho de migração e os utilitários por nome:

Antes de começar

Antes de instalar o UCX e executar os fluxos de trabalho do UCX, seu ambiente deve atender aos requisitos a seguir.

Pacotes instalados no computador em que você executa o UCX:

• CLI do Databricks v0.213 ou superior. Confira Instalar ou atualizar a CLI do Databricks.

  Você deve ter um arquivo de configuração do Databricks com perfis de configuração para o workspace e a conta do Databricks.

• Python 3.10 ou superior.

• Se quiser executar o fluxo de trabalho do UCX que identifica os locais de armazenamento usados pelas tabelas do Hive em seu workspace (recomendado, mas não obrigatório), você deverá ter a CLI do seu provedor de armazenamento em nuvem (CLI do Azure ou CLI da AWS) instalada no computador em que executa os fluxos de trabalho do UCX.

Acesso à rede:

• Acesso à rede do computador que executa a instalação do UCX para o workspace do Azure Databricks que você está migrando.
• Acesso à rede de Internet a partir do computador que executa a instalação do UCX. Isso é necessário para acessar o pypi.org e o github.com.
• Acesso à rede a partir do workspace do Azure Databricks para pypi.org para baixar os pacotes databricks-sdk e pyyaml.

Funções e permissões do Databricks:

• Funções de administrador da conta do Azure Databricks e de administrador do workspace para o usuário que executa a instalação do UCX. Você não pode executar a instalação como uma entidade de serviço.

Outros pré-requisitos do Databricks:

• Um metastore do Catálogo do Unity criado para cada região que hospeda um workspace que você quer atualizar, com cada um desses workspaces do Azure Databricks anexado a um metastore do Catálogo do Unity.

  Para saber como determinar se você já tem um metastore do Catálogo do Unity nas regiões relevantes do workspace, como criar um metastore se não tiver e como anexar um metastore do Catálogo do Unity a um workspace, confira Etapa 1: confirmar se o workspace está habilitado para o Catálogo do Unity no artigo de configuração do Catálogo do Unity. Como alternativa, o UCX fornece um utilitário para atribuir metastores do Catálogo do Unity a workspaces que você pode usar após a instalação do UCX.

  Anexar um metastore do Catálogo do Unity a um workspace também permite a federação de identidade, na qual você centraliza o gerenciamento de usuários no nível da conta do Azure Databricks, o que também é um pré-requisito para usar o UCX. Confira Habilitar a federação de identidade.

• Se o workspace usar um metastore do Hive externo (como o AWS Glue) em vez do metastore do Hive local do workspace padrão, você deverá executar alguma configuração de pré-requisito. Confira Integração do metastore do Hive externo no repositório databrickslabs/ucx.

• Um warehouse SQL Pro ou sem servidor em execução no workspace em que você executa fluxos de trabalho do UCX, necessário para renderizar o relatório gerado pelo fluxo de trabalho de avaliação.

Instalar o UCX

Para instalar o UCX, use a CLI do Databricks:

databricks labs install ucx

Você será solicitado a selecionar o seguinte:

1. O perfil de configuração do Databricks para o workspace que você quer atualizar. O arquivo de configuração também deve incluir um perfil de configuração para a conta pai do Databricks do workspace.

2. Um nome para o banco de dados de inventário que será usado para armazenar a saída dos fluxos de trabalho de migração. Normalmente, não há problema em selecionar o padrão, que é ucx.

3. Um warehouse SQL para executar o processo de instalação.

4. Uma lista de grupos locais do workspace que você quer migrar para grupos em nível de conta. Se você deixar essa opção como padrão (<ALL>), qualquer grupo existente no nível da conta cujo nome corresponda a um grupo local do workspace será tratado como substituto desse grupo local do workspace e herdará todas as suas permissões de workspace quando você executar o fluxo de trabalho de migração de grupo após a instalação.

   Você tem a oportunidade de modificar o mapeamento de grupo de workspace para grupo de conta depois de executar o instalador e antes de executar a migração de grupo. Confira Resolução de conflitos de nome de grupo no repositório UCX.

5. Se você tiver um metastore do Hive externo, como o AWS Glue, terá a opção de se conectar a ele ou não. Confira Integração do metastore do Hive externo no repositório databrickslabs/ucx.

6. Se o bloco de anotações README gerado deve ser aberto.

Quando a instalação é concluída, ele implanta um bloco de anotações README, painéis, bancos de dados, bibliotecas, trabalhos e outros ativos em seu workspace.

Para obter mais informações, confira as instruções de instalação no README do projeto. Você também pode instalar o UCX em todos os workspaces em sua conta do Databricks.

Abrir o bloco de anotações README

Cada instalação cria um bloco de anotações README que fornece uma descrição detalhada de todos os fluxos de trabalho e tarefas, com links rápidos para os fluxos de trabalho e painéis. Confira Bloco de anotações README.

Etapa 1. Executar o fluxo de trabalho de avaliação

O fluxo de trabalho de avaliação avalia a compatibilidade do Catálogo do Unity de identidades de grupo, locais de armazenamento, credenciais de armazenamento, controles de acesso e tabelas no workspace atual e fornece as informações necessárias para planejar a migração para o Catálogo do Unity. As tarefas no fluxo de trabalho de avaliação podem ser executadas em paralelo ou sequencialmente, dependendo das dependências especificadas. Após a conclusão do fluxo de trabalho da avaliação, um painel de avaliação é preenchido com descobertas e recomendações comuns.

A saída de cada tarefa de fluxo de trabalho é armazenada em tabelas Delta no esquema $inventory_database especificado durante a instalação. Você pode usar essas tabelas para executar análises adicionais e tomar decisões usando um relatório de avaliação. Você pode executar o fluxo de trabalho de avaliação várias vezes para garantir que todas as entidades incompatíveis sejam identificadas e contabilizadas antes de iniciar o processo de migração.

Você pode acionar o fluxo de trabalho de avaliação no bloco de anotações README gerado pelo UCX e na interface do usuário do Azure Databricks (Fluxos de Trabalho > Trabalhos > Avaliação [UCX]) ou executar o seguinte comando da CLI do Databricks:

databricks labs ucx ensure-assessment-run

Para obter instruções detalhadas, confira Fluxo de trabalho de avaliação.

Etapa 2. Executar o fluxo de trabalho de migração de grupo

O fluxo de trabalho de migração de grupo atualiza grupos locais de workspace para grupos de nível de conta para dar suporte ao Catálogo do Unity. Ele garante que os grupos de nível de conta apropriados estejam disponíveis no workspace e replica todas as permissões. Ele também remove grupos e permissões desnecessários do workspace. As tarefas no fluxo de trabalho de migração de grupo dependem da saída do fluxo de trabalho de avaliação.

A saída de cada tarefa de fluxo de trabalho é armazenada em tabelas Delta no esquema $inventory_database especificado durante a instalação. Você pode usar essas tabelas para executar análises adicionais e tomadas de decisão. Você pode executar o fluxo de trabalho de migração de grupo várias vezes para garantir que todos os grupos sejam atualizados com sucesso e que todas as permissões necessárias sejam atribuídas.

Para obter informações sobre a execução do fluxo de trabalho de migração de grupo, confira o bloco de anotações README gerado pelo UCX e o fluxo de trabalho de migração de grupo no README do UCX.

Etapa 3. Executar o fluxo de trabalho de migração de tabela

O fluxo de trabalho de migração de tabela atualiza tabelas do metastore do Hive para o metastore do Catálogo do Unity. As tabelas externas no metastore do Hive são atualizadas como tabelas externas no Catálogo do Unity, usando SYNC. As tabelas gerenciadas no metastore do Hive armazenadas no armazenamento do workspace (também conhecido como raiz DBFS) são atualizadas como tabelas gerenciadas no Catálogo do Unity, usando DEEP CLONE.

As tabelas gerenciadas do Hive devem estar no formato Delta ou Parquet para serem atualizadas. As tabelas externas do Hive devem estar em um dos formatos de dados listados em Trabalhar com tabelas externas.

Executar os comandos preparatórios

A migração de tabela inclui várias tarefas preparatórias executadas antes de executar o fluxo de trabalho de migração de tabela. Execute essas tarefas usando os seguintes comandos da CLI do Databricks:

• O comando create-table-mapping, que cria um arquivo CSV que mapeia um catálogo, um esquema e uma tabela de destino do Catálogo do Unity para cada tabela do Hive que será atualizada. Você deve examinar e atualizar o arquivo de mapeamento antes de prosseguir com o fluxo de trabalho de migração.
• O comando create-uber-principal, que cria uma entidade de serviço com acesso somente leitura a todo o armazenamento usado pelas tabelas nesse workspace. O recurso de computação de trabalho de fluxo de trabalho usa essa entidade de segurança para atualizar as tabelas no workspace. Desprovisione essa entidade de serviço quando terminar de atualizar.
• (Opcional) O comando principal-prefix-access, que identifica as contas de armazenamento e as credenciais de acesso de armazenamento usadas pelas tabelas do Hive no workspace.
• (Opcional) O comando migrate-credentials, que cria credenciais de armazenamento do Catálogo do Unity com base nas credenciais de acesso de armazenamento identificadas por principal-prefix-access.
• (Opcional) O comando migration locations, que cria locais externos do Catálogo do Unity a partir dos locais de armazenamento identificados pelo fluxo de trabalho de avaliação, usando as credenciais de armazenamento criadas por migrate-credentials.
• (Opcional) O comando create-catalogs-schemas, que cria catálogos e esquemas do Catálogo do Unity que conterão as tabelas atualizadas.

Para obter detalhes, incluindo comandos e opções adicionais de fluxo de trabalho de migração de tabela, confira Comandos de migração de tabela no README UCX.

Executar a migração da tabela

Depois de executar as tarefas preparatórias, você pode executar o fluxo de trabalho de migração de tabela no bloco de anotações README gerado pelo UCX ou em Fluxos de Trabalho > Trabalhos na interface do usuário do workspace.

A saída de cada tarefa de fluxo de trabalho é armazenada em tabelas Delta no esquema $inventory_database especificado durante a instalação. Você pode usar essas tabelas para executar análises adicionais e tomadas de decisão. Talvez seja necessário executar o fluxo de trabalho de migração de tabela várias vezes para garantir que todas as tabelas sejam atualizadas com sucesso.

Para obter instruções de migração de tabela completas, confira o bloco de anotações README gerado pelo UCX e o fluxo de trabalho de migração de tabela no README do UCX.

Ferramentas adicionais

O UCX também inclui ferramentas de depuração e outros utilitários para lhe ajudar a ter sucesso com sua migração. Para obter mais informações, confira o bloco de anotações README gerado pelo UCX e o README do projeto UCX.

Atualizar a instalação do UCX

O projeto UCX é atualizado regularmente. Para atualizar sua instalação do UCX para a versão mais recente:

1. Verifique se o UCX está instalado.

   databricks labs installed
   
   Name  Description                            Version
   ucx   Unity Catalog Migration Toolkit (UCX)  0.20.0
   

2. Execute a atualização:

   databricks labs upgrade ucx
   

Obter ajuda

Para obter ajuda com a CLI do UCX, execute:

databricks labs ucx --help

Para obter ajuda com um comando UCX específico, execute:

databricks labs ucx <command> --help

Para solucionar problemas:

• Execute --debug com qualquer comando para habilitar os logs de depuração.
• Use o bloco de anotações de depuração gerado automaticamente pelo UCX.

Para registrar um problema ou solicitação de recurso, registre um problema do GitHub.

Notas sobre a versão do UCX

Confira o changelog no repositório GitHub do UCX.