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.

nota

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 garantias de nenhum tipo. 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 suporte.

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

1. Avaliação de fluxo de trabalho para ajudar o senhor a planejar sua migração.
2. 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.
3. 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:

nota

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), é necessário ter o CLI do provedor de armazenamento em nuvem (Azure CLI ou AWS CLI) instalado no computador em que o fluxo de trabalho do UCX for executado.

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 pypi.org e 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 anexado 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 Etapa 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 identidades.

• 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 no repositório databrickslabs/ucx.

• Um SQL warehouse Pro ou sem servidor 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.

Instale o UCX

Para instalar o UCX, use a CLI do Databricks:

Bash

databricks labs install ucx

Você será solicitado a selecionar o seguinte:

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

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

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

4. 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 repositório UCX.

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

6. Se deve abrir o README Notebook gerado.

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 links rápidos para os fluxos de trabalho e dashboards. Consulte o Readme Notebook.

Etapa 1. execução da avaliação do 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 no fluxo de trabalho de avaliação 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 Notebook gerado pelo UCX e da interface do usuário Databricks (fluxo de trabalho > Jobs > [UCX] Assessment) ou executar o seguinte comando Databricks CLI :

Bash

databricks labs ucx ensure-assessment-run

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

Etapa 2. execução do fluxo de trabalho de migração do grupo

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 README Notebook gerado pelo UCX e o fluxo de trabalho de migração de grupo no readme do UCX.

Etapa 3. execução da tabela de migração de 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 de destino do Unity Catalog 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, inclusive 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 no README Notebook gerado pelo UCX ou em fluxo de trabalho > Jobs na interface do usuário 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 README Notebook gerado pelo UCX e o fluxo de trabalho de migração de tabelas no readme do UCX.

Ferramentas adicionais

O UCX também inclui:

• utilidades para habilitar a federaçãoHive metastore, a ferramenta de integração Databricks que permite que o Unity Catalog governe tabelas registradas em um Hive metastore:

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

  Hive metastore A federação auxilia na migração, permitindo que o senhor execute cargas de trabalho tanto no site legado Hive metastore quanto no espelho dele em Unity Catalog, facilitando a transição para Unity Catalog. Para obter mais informações sobre o uso da federação Hive metastore em um cenário de migração, consulte Como o senhor usa a federação Hive metastore durante a migração para 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 o README Notebook gerado pelo UCX e o readme do projeto UCX.

Atualize sua instalação 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.

   Bash

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

2. executar o upgrade:

   Bash

   databricks labs upgrade ucx

Obtenha ajuda

Para obter ajuda com o UCX CLI, execute:

Bash

databricks labs ucx --help

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

Bash

databricks labs ucx <command> --help

Para solucionar problemas:

• execução --debug com qualquer comando para ativar a depuração logs.
• Use o Notebook de depuração 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

Veja o registro de alterações no repositório do GitHub do UCX.