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.

Nota

O UCX, como todos os projetos na conta do GitHub databrickslabs, é fornecido apenas para sua exploração e não é formalmente suportado pelo Databricks com contratos de nível de serviço (SLAs). É fornecido no estado em que se encontra. Não damos qualquer tipo de garantia. Não envie um ticket de suporte do Databricks relacionado a problemas que surjam do uso deste projeto. Em vez disso, registre um problema no GitHub. Os problemas serão revisados conforme o tempo permitir, mas não há SLAs formais para suporte.

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 grupo para ajudá-lo a atualizar a associação de grupo do seu espaço de trabalho para sua conta do Databricks e migrar 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 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:

Nota

O fluxo de trabalho de migração de código descrito no diagrama permanece em desenvolvimento e ainda não está disponível.

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 do Azure Databricks para pypi.org para transferir os databricks-sdk pacotes 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 uma entidade de serviço.

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 no repositório databrickslabs/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 arquivo de configuração também deve incluir um perfil de configuração para a conta Databricks pai 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 nome de grupo 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 deseja abrir o bloco de anotações LEIA-ME gerado.

Quando a instalação é concluída, ele implanta um bloco de anotações LEIA-ME, painéis, bancos de dados, bibliotecas, trabalhos e outros ativos em 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 bloco de notas LEIA-ME

Cada instalação cria um bloco de anotações LEIA-ME 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. 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 especificado durante a $inventory_database 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.

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

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 grupo atualiza grupos locais do espaço de trabalho para grupos no nível da conta para oferecer suporte ao Catálogo Unity. 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 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 especificado durante a $inventory_database 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 gerenciadas no metastore do Hive armazenadas no armazenamento do espaço de trabalho (também conhecido como raiz DBFS) são atualizadas como tabelas gerenciadas no Unity Catalog, usando o 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 create-table-mapping comando, que cria um arquivo CSV que mapeia um catálogo, esquema e tabela do Unity Catalog de destino para 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 create-uber-principal comando, que cria uma entidade de serviço com acesso somente leitura a todo o armazenamento usado 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. Desprovisione esta entidade de serviço quando terminar 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 de > Fluxos de Trabalho 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 especificado durante a $inventory_database 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 sobre migração de tabelas, consulte seu 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 ajudá-lo a ter sucesso com sua migração. Para obter mais informações, consulte seu bloco de anotações README gerado pela UCX e o readme 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 --debug com qualquer comando para ativar logs de depuração.
• Use o bloco de anotações de depuração que é gerado automaticamente pelo UCX.

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.