Use as utilidades do UCX para atualizar seu workspace para Unity Catalog

Este artigo apresenta o UCX, um projeto do Databricks Labs que fornece ferramentas para ajudá-lo a atualizar seu catálogo não-Unity workspace para Unity Catalog.

Observação

O UCX, como todos os projetos do databrickslabs GitHub account, é fornecido apenas para sua exploração e não é formalmente suportado pelo Databricks com acordos de nível de serviço (SLAs). Ele é fornecido no estado em que se encontra. Não oferecemos nenhum tipo de garantia. Não envie um tíquete de suporte da Databricks relacionado a problemas decorrentes do uso deste projeto. Em vez disso, registre um problema no GitHub. Os problemas serão analisados conforme o tempo permitir, mas não há SLAs formais para o suporte.

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

Avaliação de fluxo de trabalho para ajudar o senhor a planejar sua migração.
O fluxo de trabalho de migração de grupos ajuda o senhor a atualizar a associação de grupos de workspace para Databricks account e a migrar as permissões para os novos grupos de nível account.
Fluxo de trabalho de migração de tabelas para ajudá-lo a atualizar as tabelas registradas no workspace Hive metastore para o metastore Unity Catalog. Esse fluxo de trabalho também ajuda o senhor a migrar os locais de armazenamento e as credenciais necessárias para acessá-los.

Esse diagrama mostra o fluxo geral de migração, identificando o fluxo de trabalho e as utilidades por nome:

Gráfico de fluxo de trabalho de migração da UCX

Observação

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

Antes de começar

Antes que o senhor possa instalar o UCX e executar o fluxo de trabalho do UCX, seu ambiente deve atender aos seguintes requisitos.

pacote instalado no computador em que o senhor executa o UCX:

Databricks CLI v0.213 ou acima. Consulte Instalar ou atualizar a CLI da Databricks.

O senhor deve ter um arquivo de configuração Databricks com perfis de configuração para o workspace e o Databricks account.
Python 3,10 ou acima.
Se quiser executar o fluxo de trabalho do UCX que identifica os locais de armazenamento usados pelas tabelas Hive em seu workspace (recomendado, mas não obrigatório), o usuário deverá ter o CLI do provedor de armazenamento cloud (Azure CLI ou AWS CLI) instalado no computador em que estiver executando o fluxo de trabalho do UCX.

Acesso à rede:

Acesso à rede do computador que executa a instalação do UCX para o Databricks workspace que o senhor está migrando.
Acesso à rede da 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 do seu Databricks workspace para pypi.org para download o pacote databricks-sdk e pyyaml.

Funções e permissões do Databricks:

Databricks account admin e workspace admin para o usuário que executa a instalação do UCX. O senhor não pode executar a instalação como uma entidade de serviço.

Outros pré-requisitos do Databricks:

Um metastore Unity Catalog criado para cada região que hospeda um workspace que o senhor deseja atualizar, com cada um desses espaços de trabalho Databricks anexados a um metastore Unity Catalog.

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

Anexar um metastore Unity Catalog a um workspace também permite a federação de identidade, na qual o senhor centraliza o gerenciamento de usuários no nível Databricks account , o que também é um pré-requisito para o uso do UCX. Consulte Habilitar federação de identidade.
Se o seu workspace usar um Hive metastore externo (como o AWS Glue) em vez do default workspace-local Hive metastore, o senhor deverá realizar algumas configurações prévias. Consulte Integração com o site Hive metastore externo em databrickslabs/ucx repo.
Um Pro ou serverless SQL warehouse em execução no workspace onde o senhor executa o fluxo 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

O senhor é solicitado a selecionar o seguinte:

O perfil de configuração Databricks para o workspace que o senhor deseja atualizar. O arquivo de configuração também deve incluir um perfil de configuração para o workspace's parent Databricks account.
Um nome para o banco de dados de inventário que será usado para armazenar a saída da migração do fluxo de trabalho. Normalmente, não há problema em selecionar o default, que é ucx.
A SQL warehouse para executar o processo de instalação.
Uma lista de workspace-local groups que o senhor deseja migrar para account-level groups. Se o senhor deixar essa opção como default (<ALL>), qualquer grupo de nível accountexistente cujo nome corresponda a um grupo workspace-local será tratado como substituto desse grupo workspace-local e herdará todas as suas permissões workspace quando o senhor executar o fluxo de trabalho de migração de grupo após a instalação.

O senhor tem a oportunidade de modificar o mapeamento workspace-group-to-account-group depois de executar o instalador e antes de executar a migração de grupo. Consulte Resolução de conflitos de nomes de grupos no UCX repo.
Se o senhor tiver um Hive metastore externo, como o AWS Glue, terá a opção de se conectar a ele ou não. Consulte Integração com o site Hive metastore externo em databrickslabs/ucx repo.
Se o senhor deve abrir o README gerado Notebook.

Quando a instalação é concluída, ele implanta um README Notebook, dashboards, bancos de dados, biblioteca, Job e outros ativos em seu site workspace.

Para obter mais informações, consulte as instruções de instalação no leia-me do projeto. O senhor também pode instalar o UCX em todo o espaço de trabalho em seu site Databricks account .

Abra o README Notebook

Toda instalação cria um README Notebook que fornece uma descrição detalhada de todos os fluxos de trabalho e tarefas, com Quick Links para os fluxos de trabalho e painéis. Consulte o Readme Notebook.

o passo 1. execução da avaliação fluxo de trabalho

O fluxo de trabalho de avaliação avalia a compatibilidade Unity Catalog de identidades de grupo, locais de armazenamento, credenciais de armazenamento, controles de acesso e tabelas no site workspace atual e fornece as informações necessárias para planejar a migração para Unity Catalog. A tarefa na avaliação do fluxo de trabalho pode ser executada 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 o senhor especifica durante a instalação. O senhor pode usar essas tabelas para realizar análises adicionais e tomar decisões usando um relatório de avaliação. O senhor pode executar a avaliação fluxo de trabalho várias vezes para garantir que todas as entidades incompatíveis sejam identificadas e contabilizadas antes de iniciar o processo de migração.

O senhor pode acionar o fluxo de trabalho de avaliação a partir do README gerado pelo UCX Notebook e da interface do usuário Databricks (fluxo de trabalho > Jobs > [UCX] Assessment), ou executar o seguinte comando Databricks CLI :

databricks labs ucx ensure-assessment-run

Para obter instruções detalhadas, consulte Avaliação do fluxo de trabalho.

o passo 2. execução the group migration fluxo de trabalho

O fluxo de trabalho de migração de grupo atualiza os grupos workspace-local para grupos de nível accountpara suportar Unity Catalog. Ele garante que os grupos de nível accountapropriados estejam disponíveis no site workspace e replica todas as permissões. Ele também remove todos os grupos e permissões desnecessários do site workspace. A tarefa no grupo de migração fluxo de trabalho depende do resultado da avaliação fluxo de trabalho.

A saída de cada tarefa de fluxo de trabalho é armazenada em tabelas Delta no esquema $inventory_database que o senhor especifica durante a instalação. O senhor pode usar essas tabelas para realizar análises adicionais e tomar decisões. O senhor pode executar o fluxo de trabalho de migração de grupos 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 a execução do fluxo de trabalho de migração de grupo, consulte o LEIAME gerado pelo UCX Notebook e o fluxo de trabalho de migração de grupo no LEIAME do UCX.

o passo 3. execução the table migration fluxo de trabalho

O fluxo de trabalho de migração de tabelas atualiza as tabelas do Hive metastore para o metastore Unity Catalog. As tabelas externas no site Hive metastore são atualizadas como tabelas externas no site Unity Catalog, usando SYNC. As tabelas gerenciáveis em Hive metastore que estão armazenadas no storage workspace (também conhecido como DBFS root) são atualizadas como tabelas gerenciáveis em Unity Catalog, usando o DEEP CLONE.

Hive As tabelas gerenciar 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.

execução do comando preparatório

A migração de tabelas inclui uma série de tarefas preparatórias que devem ser executadas antes da execução do fluxo de trabalho de migração de tabelas. O senhor realiza essas tarefas usando o seguinte Databricks CLI comando:

O comando create-table-mapping, que cria um arquivo CSV que mapeia um catálogo, um esquema e uma tabela do Unity Catalog de destino para cada tabela do Hive que será atualizada. O senhor 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 uma entidade de serviço com acesso somente leitura a todo o armazenamento usado pelas tabelas neste workspace. O fluxo de trabalho Job compute recurso usa esse princípio para atualizar as tabelas no site workspace. Desprovisione essa entidade de serviço quando o senhor terminar o upgrade.
(Opcional) O comando principal-prefix-access, que identifica a conta de armazenamento e as credenciais de acesso ao armazenamento usadas pelas tabelas Hive no site workspace.
(Opcional) O comando migrate-credentials, que cria credenciais de armazenamento do Unity Catalog a partir das credenciais de acesso ao armazenamento identificadas por principal-prefix-access.
(Opcional) O comando migration locations, 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 por migrate-credentials.
(Opcional) O comando create-catalogs-schemas, que cria catálogos e esquemas do Unity Catalog que conterão as tabelas atualizadas.

Para obter detalhes, incluindo opções e fluxo de trabalho de migração de tabela adicionais, consulte Table migration comando no readme do UCX.

execução da migração da tabela

Depois de executar a tarefa preparatória, o senhor pode executar o fluxo de trabalho de migração da tabela a partir do README gerado pelo UCX Notebook ou do fluxo de trabalho > Jobs na UI workspace.

A saída de cada tarefa de fluxo de trabalho é armazenada em tabelas Delta no esquema $inventory_database que o senhor especifica durante a instalação. O senhor pode usar essas tabelas para realizar análises adicionais e tomar decisões. Talvez o senhor precise 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 a migração de tabelas, consulte o LEIAME gerado pelo UCX Notebook e o fluxo de trabalho de migração de tabelas no LEIAME do UCX.

Ferramentas adicionais

O UCX também inclui ferramentas de depuração e outros utilitários para ajudar o senhor a ter sucesso na migração. Para obter mais informações, consulte o README gerado pelo UCX Notebook e o readme do projeto UCX.

Atualize sua instalação do UCX

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

Verifique se o UCX está instalado.

databricks labs installed

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

executar o upgrade:
```
databricks labs upgrade ucx
```

Obter ajuda

Para obter ajuda com o UCX CLI, execute:

databricks labs ucx --help

Para obter ajuda com um comando, execução UCX específico:

databricks labs ucx <command> --help

Para solucionar problemas:

execução --debug com qualquer comando para ativar a depuração logs.
Use o endereço de depuração Notebook que é gerado automaticamente pelo UCX.

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

UCX notas sobre a versão

Consulte o registro de alterações no site da UCX GitHub repo.