Migrar metadados de catálogos de dados externos para tabelas do catálogo REST do Lakehouse para Apache Iceberg

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Observação :para receber suporte ou enviar feedback sobre esse recurso, entre em contato com [e-mail].

Neste documento, mostramos como migrar metadados de catálogos de dados externos para tabelas do catálogo REST do Lakehouse para Apache Iceberg. O serviço de migração do BigQuery é compatível com a migração de metadados dos seguintes metastores externos:

• Metastore do Apache Hive
• Catálogos REST do Apache Iceberg

Limitações

Aviso :modificar dados nas tabelas de origem e na tabela de destino após uma migração pode levar à perda de dados.

• As migrações de metadados de Data Catalogs externos para tabelas do catálogo REST do Lakehouse para Apache Iceberg são uma sincronização única. Esse recurso não oferece suporte a sincronizações contínuas ou periódicas. Portanto, as gravações feitas após a migração só ficam visíveis quando você migra novamente.
• Não é possível usar namespaces aninhados.
• O catálogo REST do Iceberg só aceita arquivos de dados Parquet.
• O Lakehouse sem fronteiras não é compatível com tabelas do Apache Iceberg V3.
• As migrações de metadados de catálogos de dados externos para tabelas do catálogo REST do Lakehouse para Apache Iceberg só aceitam migrações de até 10.000 tabelas. Se a carga de trabalho exigir o processamento de mais de 10.000 tabelas, recomendamos dividi-la em várias migrações.
• As migrações de metadados de Data Catalogs externos para tabelas do catálogo REST do Lakehouse para Apache Iceberg não são compatíveis com o uso de políticas da organização para aplicar o compartilhamento restrito por domínio.

Antes de começar

Antes de migrar metadados dos seus catálogos de dados externos, siga as etapas nas seções a seguir.

Ativar APIs

Ative as APIs BigLake, BigQuery Data Transfer, BigQuery Migration, Secret Manager e Storage Transfer, se ainda não estiverem ativadas.

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar as APIs

Um agente de serviço é criado quando você ativa a API Transferência de dados.

Configurar permissões

1. O usuário ou a conta de serviço que cria a transferência precisa receber o papel de administrador do BigQuery (roles/bigquery.admin). Se você usar uma conta de serviço, ela será usada apenas para criar a transferência.

2. Um agente de serviço (P4SA) é criado ao ativar a API Transferência de dados.

   Para garantir que o agente de serviço tenha as permissões necessárias para executar uma transferência do Hive Metastore, peça ao administrador para conceder os seguintes papéis do IAM ao agente de serviço no projeto:

   Importante:conceda esses papéis ao agente de serviço, não à sua conta de usuário. Se os papéis não forem concedidos ao principal correto, poderão ocorrer erros de permissão.
   • Administrador do Storage Transfer (roles/storagetransfer.admin)
   • Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer)
   • Administrador de armazenamento (roles/storage.admin)
   • Para migrar metadados para o catálogo do ambiente de execução do Lakehouse (catálogo REST do Iceberg ou catálogo do Hive): Administrador do BigLake (roles/biglake.admin)

   Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

   Seu administrador também pode conceder ao agente de serviço as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

3. Se você estiver usando uma conta de serviço, conceda ao agente de serviço o papel roles/iam.serviceAccountTokenCreator com o seguinte comando:

   gcloud iam service-accounts add-iam-policy-binding
   SERVICE_ACCOUNT --member
   serviceAccount:[e-mail] --role
   roles/iam.serviceAccountTokenCreator

4. Conceda ao agente de serviço do Serviço de transferência do Cloud Storage ([e-mail]) os seguintes papéis no projeto:

   • roles/storage.admin
   • Se você estiver migrando do local/HDFS, também precisará conceder o papel roles/storagetransfer.serviceAgent.

   Também é possível configurar permissões mais granulares. Para mais informações, consulte o guia a seguir:

   • Permissões do HDFS
   • Permissões do Amazon S3 e do Microsoft Azure

Papéis e permissões de usuário necessários

Para garantir que o agente de serviço tenha as permissões necessárias para criar, modificar e executar tabelas de catálogo REST do Lakehouse para a migração do Apache Iceberg, peça ao administrador para conceder os seguintes papéis do IAM ao agente de serviço no usuário:

Importante:conceda esses papéis ao agente de serviço, não à sua conta de usuário. Se os papéis não forem concedidos ao principal correto, poderão ocorrer erros de permissão.

• Usuário da conta de serviço (roles/iam.serviceAccountUser)
• Editor de gerenciamento de migração (roles/bigquerymigration.migrationEditor)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Seu administrador também pode conceder ao agente de serviço as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

Papéis e permissões necessários da conta de serviço

Para garantir que a conta de serviço fornecida pelo cliente tenha as permissões necessárias para criar, modificar e executar tabelas de catálogo REST do Lakehouse para a migração do Apache Iceberg, peça ao administrador para conceder os seguintes papéis do IAM à conta de serviço fornecida pelo cliente:

Importante:conceda esses papéis à conta de serviço fornecida pelo cliente, não à sua conta de usuário. Se os papéis não forem concedidos ao principal correto, poderão ocorrer erros de permissão.

• Acesso ao anexo de rede: Administrador de rede do Compute (roles/compute.networkAdmin) na conta de serviço
• Acesso ao serviço de transferência de dados do BigQuery: Administrador do BigQuery (roles/bigquery.admin) na conta de serviço
• Acesso aos recursos do Lakehouse: Editor do BigLake (roles/biglake.editor) na conta de serviço
• Acesso a secrets: Acessador de secrets do Secret Manager (roles/secretmanager.secretAccessor) no secret fornecido pelo cliente

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

O administrador também pode conceder à conta de serviço fornecida pelo cliente as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Também é necessário criar uma identidade de serviço para o BigQuery Migration Service e conceder a ela o papel roles/iam.serviceAccountTokenCreator.

Para criar a identidade de serviço, execute o seguinte comando:

gcloud beta services identity create --service=bigquerymigration.googleapis.com --project=PROJECT_ID

Para conceder o papel ao agente de serviço, execute o seguinte comando:

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT --member serviceAccount:[e-mail] --role roles/iam.serviceAccountTokenCreator --project PROJECT_ID

Substitua:

• SERVICE_ACCOUNT: o ID da conta de serviço fornecida pelo cliente.
• PROJECT_ID: o ID do projeto;
• PROJECT_NUMBER: o número do projeto.

Configurar secret

Se você estiver migrando para um catálogo REST do Apache Iceberg, crie um secret para autorizar a migração. O secret precisa estar no seguinte formato:

{
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "polaris_realm": "POLARIS_REALM",
  "scope": "SCOPE"
}

Substitua:

• CLIENT_ID: o ID do cliente OAuth 2.0
• CLIENT_SECRET: a chave secreta do cliente OAuth 2.0.
• POLARIS_REALM: o realm do catálogo do Polaris. Esse campo é obrigatório apenas para o Apache Polaris. Por exemplo, FINANCE.
• SCOPE: (opcional) o escopo do OAuth 2.0. O valor padrão é PRINCIPAL_ROLE:ALL.

Criar um catálogo do Lakehouse

Crie um catálogo do Lakehouse. Os metadados migrados são armazenados no bucket do Cloud Storage que você especificou ao criar o catálogo.

Migrar metadados

Para iniciar uma migração de metadados para tabelas do catálogo REST do Lakehouse Iceberg, faça o seguinte:

1. No console do Google Cloud , acesse a página Migração > Serviços.

   Acessar os Serviços de migração

2. Em Registrar ou migrar o Open Lakehouse, clique em Criar migração.

3. Em Configuração da migração, faça o seguinte:

   1. Em "Tipo de catálogo", selecione um catálogo externo.

   2. Em Região, selecione uma região. A região selecionada determina onde a orquestração da migração e a transferência de dados são executadas. Ele também determina onde o serviço de migração usa ou cria recursos, como anexos de rede ou secrets.

      Somente secrets regionais são compatíveis. A região do secret precisa corresponder à região neste campo.

   3. Em Nome de exibição da migração, insira um nome para essa migração.

4. Em Configuração do sistema de origem, faça o seguinte:

   1. Em URL, insira o URL do endpoint base que atua como o ponto de entrada para o metastore do Apache Iceberg ou do Apache Hive.
   2. Em Conta de serviço, selecione uma conta de serviço na lista. Se não for especificado, essa migração será executada usando a credencial do usuário.
   3. (Opcional) Em Anexo de rede, selecione um anexo de rede.

5. Clique em Continuar.

Quando a migração de metadados é concluída, os metadados dos seus catálogos externos são armazenados no bucket do Cloud Storage que você especificou ao criar o catálogo do Lakehouse.

Preços

Não há custo para transferir metadados para tabelas do catálogo REST do Lakehouse Iceberg. Depois que os metadados forem transferidos, os preços do Lakehouse serão aplicados.