Use os utilitários UCX para atualizar seu espaço de trabalho para o Unity Catalog

Este artigo apresenta o UCX, um projeto do Databricks Labs que fornece ferramentas para ajudá-lo a atualizar seu espaço de trabalho que não é do Unity-Catalog para o Unity Catalog.

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

1. Fluxo de trabalho de avaliação para ajudá-lo a planejar sua migração.
2. Fluxo de trabalho de migração de grupos para o ajudar a atualizar a pertença a grupos do seu espaço de trabalho para a sua conta Databricks e migrar permissões para os novos grupos ao 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 seu espaço de trabalho para o metastore do Unity Catalog. Esse fluxo de trabalho também ajuda a migrar locais de armazenamento e as credenciais necessárias para acessá-los.

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

Para obter uma demonstração de como atualizar seu espaço de trabalho usando UXC, consulte Atualização de esquema usando UCX.

Antes de começar

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

Pacotes instalados no computador onde você executa o UCX:

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

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

• Python 3.10 ou superior.

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

Acesso à rede:

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

Funções e permissões do Databricks:

• Funções de administrador de conta e administrador de espaço de trabalho do Azure Databricks para o usuário que executa a instalação do UCX. Não é possível executar a instalação como service principal.

Outros pré-requisitos do Databricks:

• Um metastore do Unity Catalog criado para cada região que hospeda um espaço de trabalho que você deseja atualizar, com cada um desses espaços de trabalho do Azure Databricks anexados a um metastore do Unity Catalog.

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

  Anexar um metastore do Unity Catalog a um espaço de trabalho também habilita a federação de identidades, na qual você centraliza o gerenciamento de usuários no nível da conta do Azure Databricks, que também é um pré-requisito para usar o UCX. Consulte Habilitar federação de identidades.

• Se seu espaço de trabalho usar um metastore externo do Hive (como o AWS Glue) em vez do metastore padrão do Hive local do espaço de trabalho, você deverá executar algumas configurações de pré-requisitos. Consulte External Hive Metastore Integration na documentação do UCX.

• Um armazém SQL Pro ou Serverless em execução no espaço de trabalho onde você executa fluxos de trabalho UCX, necessários para renderizar o relatório gerado pelo fluxo de trabalho de avaliação.

Instalar 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 espaço de trabalho que você deseja atualizar. O ficheiro de configuração também deve incluir um perfil de configuração para a conta Databricks principal do espaço de trabalho.

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 armazém SQL para executar o processo de instalação.

4. Uma lista de grupos locais do espaço de trabalho que você deseja migrar para grupos no nível da conta. Se você deixar isso como padrão (<ALL>), qualquer grupo de nível de conta existente cujo nome corresponda a um grupo local de espaço de trabalho será tratado como o substituto desse grupo local de espaço de trabalho e herdará todas as suas permissões de espaço de trabalho 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 espaço de trabalho para grupo de conta depois de executar o instalador e antes de executar a migração de grupo. Consulte Resolução de Conflitos de Nomes de Grupos no repositório UCX.

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

6. Se pretende abrir o caderno README gerado.

Quando a instalação estiver concluída, instala um notebook README, painéis, bases de dados, bibliotecas, tarefas e outros recursos no seu espaço de trabalho.

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

Abrir o notebook README

Cada instalação cria um caderno README que fornece uma descrição detalhada de todos os fluxos de trabalho e tarefas, com ligações rápidas para os fluxos de trabalho e painéis de controlo. Consulte Bloco de anotações Leiame.

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

O fluxo de trabalho de avaliação avalia a compatibilidade do Catálogo Unity de identidades de grupo, locais de armazenamento, credenciais de armazenamento, controles de acesso e tabelas no espaço de trabalho atual e fornece as informações necessárias para planejar a migração para o Catálogo 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 de 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 que especifica durante a instalação. Você pode usar essas tabelas para realizar análises e tomadas de decisão adicionais 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.

Pode iniciar o fluxo de trabalho de avaliação a partir do notebook README gerado pelo UCX e da IU do Azure Databricks (Fluxos de trabalho > Tarefas > [UCX] Assessment), ou executar o seguinte comando da Databricks CLI:

databricks labs ucx ensure-assessment-run

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

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

O fluxo de trabalho de migração de grupos atualiza grupos locais da área de trabalho para grupos ao nível da conta para suportar o Unity Catalog. Ele garante que os grupos de nível de conta apropriados estejam disponíveis no espaço de trabalho e replica todas as permissões. Ele também remove quaisquer grupos e permissões desnecessários do espaço de trabalho. As tarefas no fluxo de trabalho de migração de grupos dependem do resultado 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 que especifica durante a instalação. Você pode usar essas tabelas para realizar análises e tomadas de decisão adicionais. Você pode executar o fluxo de trabalho de migração de grupo várias vezes para garantir que todos os grupos sejam atualizados com êxito e que todas as permissões necessárias sejam atribuídas.

Para obter informações sobre como executar o fluxo de trabalho de migração de grupo, consulte seu bloco de anotações README gerado pelo UCX e o fluxo de trabalho de migração de grupo no Leiame do UCX.

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

O fluxo de trabalho de migração de tabelas atualiza as tabelas do metastore do Hive para o metastore do Unity Catalog. As tabelas externas no metastore do Hive são atualizadas como tabelas externas no Unity Catalog, usando SYNC. As tabelas geridas no metastore do Hive armazenadas no armazenamento da área de trabalho (também conhecido como raiz do DBFS) são convertidas em tabelas geridas no Unity Catalog, utilizando DEEP CLONE.

As tabelas gerenciadas pelo Hive devem estar no formato Delta ou Parquet para serem atualizadas. As tabelas do Hive externo 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 que você executa 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 ficheiro CSV que estabelece a correspondência entre um catálogo, esquema e tabela de destino do Unity Catalog e cada tabela do Hive que será atualizada. Você deve revisar e atualizar o arquivo de mapeamento antes de prosseguir com o fluxo de trabalho de migração.
• O comando create-uber-principal, que cria um principal de serviço com acesso só de leitura a todo o armazenamento utilizado pelas tabelas neste espaço de trabalho. O recurso de computação do trabalho de fluxo de trabalho usa essa entidade para atualizar as tabelas no espaço de trabalho. Desative o aprovisionamento deste principal de serviço quando concluir a atualização.
• (Opcional) O principal-prefix-access comando, que identifica as contas de armazenamento e as credenciais de acesso ao armazenamento usadas pelas tabelas do Hive no espaço de trabalho.
• (Opcional) O migrate-credentials comando, que cria credenciais de armazenamento do Unity Catalog a partir das credenciais de acesso ao armazenamento identificadas pelo principal-prefix-access.
• (Opcional) O migration locations comando, que cria locais externos do Unity Catalog a partir dos locais de armazenamento identificados pelo fluxo de trabalho de avaliação, usando as credenciais de armazenamento criadas pelo migrate-credentials.
• (Opcional) O create-catalogs-schemascomando, que cria catálogos e esquemas do Unity Catalog que manterão as tabelas atualizadas.

Para obter detalhes, incluindo comandos e opções adicionais de fluxo de trabalho de migração de tabela, consulte Comandos de migração de tabela no Leiame 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 a partir do bloco de anotações LEIA-ME gerado pelo UCX ou de Trabalhos & Pipelines na interface do usuário do espaço de trabalho.

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

Para obter instruções completas de migração de tabela, consulte seu bloco de anotações README gerado pelo UCX e os fluxos de trabalho de migração de tabela no readme do UCX.

Ferramentas adicionais

UCX também inclui:

• Utilitários para habilitar a federação de metastore do Hive , a ferramenta de integração Azure Databricks que permite ao Unity Catalog gerir tabelas registadas em um metastore do Hive.

  • enable-hms-federation
  • create-federated-catalog

  A federação de metastore do Hive ajuda na migração, permitindo que você execute cargas de trabalho no metastore herdado do Hive e em seu espelho no Unity Catalog, facilitando a transição para o Unity Catalog. Para obter mais informações sobre como usar a federação de metastore do Hive em um cenário de migração, consulte Como usar a federação de metastore do Hive durante a migração para o Unity Catalog?.

• Ferramentas de depuração e outros utilitários para ajudá-lo a ter sucesso com sua migração.

Para obter mais informações, consulte seu bloco de anotações README gerado pelo UCX e a documentação do projeto UCX.

Atualize sua instalação UCX

O projeto UCX é atualizado regularmente. Para atualizar sua instalação 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 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 o --debug com qualquer comando para ativar logs de depuração.
• Consulte o guia de solução de problemas do UCX para obter mais detalhes.

Para arquivar um problema ou solicitação de recurso, registre um problema no GitHub.

Notas de versão do UCX

Consulte o changelog no repositório UCX GitHub.