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

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

  • As migrações de metadados de catálogos de dados 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 não ficam visíveis até que você migre novamente.
  • Namespaces aninhados não são aceitos.
  • O catálogo REST do Iceberg é compatível apenas com arquivos de dados do Parquet.
  • O Lakehouse não oferece suporte a 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 catálogos de dados externos para tabelas de 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 ao domínio.

Antes de começar

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

Ativar APIs

Ative as APIs BigLake, BigQuery Data Transfer, BigQuery Migration, Secret Manager e Storage Transfer.

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 com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o 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 Data Transfer.

Configurar permissões

  1. O usuário ou a conta de serviço que está criando 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 Data Transfer.

    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 ao agente de serviço os seguintes papéis do IAM no projeto:

    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 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:service-PROJECT_NUMBER@gcp-sa-bigquerydatatransfer.s3ns-system.iam.gserviceaccount.com --role
roles/iam.serviceAccountTokenCreator

  4. Conceda ao agente de serviço do Serviço de transferência do Cloud Storage (project-PROJECT_NUMBER@storage-transfer-service.s3ns-system.iam.gserviceaccount.com) os seguintes papéis no projeto:

    • roles/storage.admin
    • Se você estiver migrando de um ambiente local/HDFS, também será necessário conceder o papel roles/storagetransfer.serviceAgent.

    Também é possível configurar permissões mais detalhadas. Para mais informações, consulte este guia:

Permissões e funções do usuário necessárias

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 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:

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 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 para 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 migração do Apache Iceberg, peça ao administrador para conceder os seguintes papéis do IAM à conta de serviço fornecida 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 outros papéis predefinidos.

Você também precisa criar uma identidade de serviço para o BigQuery Migration Service e conceder a ela a função 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:service-PROJECT_NUMBER@gcp-sa-bqms.s3ns-system.iam.gserviceaccount.com --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 OAuth2.0. O valor padrão é PRINCIPAL_ROLE:ALL.

Criar um catálogo do Lakehouse

Criar um catálogo de lakehouse. Os metadados migrados são armazenados no bucket do Cloud Storage especificado 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 Cloud de Confiance , acesse a página Migração > Serviços.

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

      Apenas segredos regionais são aceitos. 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, digite o URL do endpoint de base que atua como ponto de entrada para o metastore do Apache Iceberg ou do Apache Hive.
    2. Em Conta de serviço, selecione uma conta 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 uma opção.

  5. Clique em Continuar.

Quando a migração de metadados for concluída, os metadados dos seus catálogos externos serão armazenados no bucket do Cloud Storage especificado ao criar o catálogo do Lakehouse.

Preços

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