Migrar tabelas de um data lake do HDFS

Este documento mostra como migrar suas tabelas de data lake do Apache Hadoop Distributed File System (HDFS) para o Trusted Cloud.

É possível usar o conector de migração de data lake do HDFS no serviço de transferência de dados do BigQuery para migrar suas tabelas do Hive e do Iceberg de várias distribuições do Hadoop, tanto em ambientes locais quanto na nuvem, para o Trusted Cloud.

Com o conector do data lake do HDFS, é possível registrar as tabelas do data lake do HDFS com o metastore do Dataproc e o metastore do BigLake usando o Cloud Storage como armazenamento subjacente dos arquivos.

O diagrama a seguir fornece uma visão geral do processo de migração de tabelas do cluster do Hadoop.

Visão geral da migração de tabelas do data lake do Hive para o BigQuery.

Limitações

As transferências de data lake do HDFS estão sujeitas às seguintes limitações:

  • Para migrar tabelas do Iceberg, registre-as no metastore do BigLake para permitir acesso de gravação para mecanismos de código aberto (como Spark ou Flink) e acesso de leitura para o BigQuery.
  • Para migrar tabelas do Hive, é preciso registrá-las no Dataproc Metastore para permitir acesso de gravação para mecanismos de código aberto e acesso de leitura para o BigQuery.
  • É necessário usar a ferramenta de linha de comando bq para migrar uma tabela de data lake do HDFS para o BigQuery.

Antes de começar

Antes de programar uma transferência de data lake do HDFS, faça o seguinte:

Criar um bucket do Cloud Storage para arquivos migrados

Crie um bucket do Cloud Storage que será o destino dos arquivos do data lake migrados. Neste documento, esse bucket é chamado de MIGRATION_BUCKET.

Arquivos obrigatórios

Você precisa ter os seguintes arquivos de migração em um bucket do Cloud Storage antes de programar uma transferência de data lake do HDFS:

  • O arquivo de metadados extraídos (hive-dumper-output.zip)
  • O arquivo YAML de configuração de tradução (*.config.yaml)
  • Os arquivos YAML de mapeamento de tabelas

As seções a seguir descrevem como criar esses arquivos.

hive-dumper-output.zip

Execute a ferramenta dwh-migration-dumper para extrair metadados do Apache Hive. A ferramenta gera um arquivo chamado hive-dumper-output.zip em um bucket do Cloud Storage, chamado neste documento de DUMPER_BUCKET.

Arquivo YAML de configuração de tradução

Crie um arquivo YAML de configuração de tradução com um nome que contenha o sufixo .config.yaml, por exemplo, translation.config.yaml, e faça upload dele para o mesmo bucket que contém hive-dumper-output.zip. Configure o YAML de configuração de tradução para mapear caminhos do HDFS para pastas gerenciadas do Cloud Storage, semelhante ao exemplo a seguir:

type: object_rewriter
relation:
- match:
    relationRegex: ".*"
  external:
    location_expression: "'gs://MIGRATION_BUCKET/' + table.schema + '/' + table.name"

Substitua MIGRATION_BUCKET pelo nome do bucket do Cloud Storage que é o destino dos arquivos migrados.

O campo location_expression é uma expressão da linguagem de expressão comum (CEL).

Para mais informações sobre esse YAML de configuração, consulte Diretrizes para criar um arquivo YAML de configuração.

Gerar arquivos YAML de mapeamento de tabelas

Para gerar um arquivo YAML de mapeamento de tabelas, execute o seguinte comando:

  curl -d '{
    "tasks": {
        "string": {
          "type": "HiveQL2BigQuery_Translation",
          "translation_details": {
              "target_base_uri": "TRANSLATION_OUTPUT_BUCKET",
              "source_target_mapping": {
                "source_spec": {
                    "base_uri": "DUMPER_BUCKET"
                }
              },
              "target_types": ["metadata"]
          }
        }
    }
    }' \
    -H "Content-Type:application/json" \
    -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows

Substitua:

  • TRANSLATION_OUTPUT_BUCKET: o URI base de um bucket do Cloud Storage para conter o arquivo YAML de mapeamento de tabelas. Por exemplo, gs://output_bucket/tables/.
  • DUMPER_BUCKET: o URI de base do bucket do Cloud Storage que contém o hive-dumper-output.zip e o arquivo YAML de configuração.
  • TOKEN: o token OAuth. É possível gerar isso na linha de comando com o comando gcloud auth print-access-token.
  • PROJECT_ID: o projeto que vai processar a tradução.
  • LOCATION: o local em que o job é processado. Por exemplo, eu ou us.

Quando executada, a API Translation Service retorna um WORKFLOW_ID e inicia um job assíncrono em segundo plano. Monitore o status desse job usando o comando a seguir:

  curl \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer TOKEN" -X GET https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Quando concluído, os arquivos YAML de mapeamento de tabelas são criados. Seus arquivos YAML de mapeamento de tabelas podem consistir em vários arquivos, um para cada tabela, armazenados na pasta do Cloud Storage.

Ativar APIs

Ative as APIs a seguir no projeto Trusted Cloud :

  • API Data Transfer
  • API Storage Transfer

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

Configurar permissões

  1. Crie uma conta de serviço e conceda a ela o papel de administrador do BigQuery (roles/bigquery.admin). Essa conta de serviço é usada para criar a configuração de transferência.
  2. Um agente de serviço (P4SA) é criado ao ativar a API Data Transfer. Conceda os seguintes papéis:
    • roles/metastore.metadataOwner
    • roles/storagetransfer.admin
    • roles/serviceusage.serviceUsageConsumer
    • roles/storage.objectViewer
      • Se você estiver migrando metadados para tabelas do BigLake Iceberg, conceda a elas as funções roles/storage.objectAdmin e roles/bigquery.admin em vez de roles/storage.objectViewer.

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

Configurar o agente de transferência do Storage

Para configurar o agente de transferência de armazenamento necessário para uma transferência de data lake do HDFS, faça o seguinte:

  1. Configure as permissões para executar o agente de transferência de armazenamento no cluster do Hadoop.
  2. Instale o Docker nas máquinas de agente locais.
  3. Crie um pool de agentes do Serviço de transferência do Cloud Storage no seu Trusted Cloud by S3NS projeto.
  4. Instale agentes nas máquinas de agentes locais.

Programar uma transferência de data lake do HDFS

Para programar uma transferência de data lake do HDFS, insira o comando bq mk e forneça a flag de criação de transferência --transfer_config:

  bq mk --transfer_config
  --data_source=hadoop
  --display_name='TRANSFER_NAME'
  --service_account_name='SERVICE_ACCOUNT'
  --project_id='PROJECT_ID'
  --location='REGION'
  --params='{"table_name_patterns":"LIST_OF_TABLES",
    "agent_pool_name":"AGENT_POOL_NAME",
    "destination_dataproc_metastore":"DATAPROC_METASTORE",
    "translation_output_gcs_path":"gs://TRANSLATION_OUTPUT_BUCKET/metadata/config/default_database/",
    "table_metadata_path":"gs://DUMPER_BUCKET/hive-dumper-output.zip"}'

Substitua:

  • TRANSFER_NAME: o nome de exibição da configuração da transferência. O nome da transferência pode ser qualquer valor que permita identificá-la, caso precise modificá-la mais tarde.
  • SERVICE_ACCOUNT: o nome da conta de serviço usado para autenticar a transferência. A conta de serviço precisa pertencer ao mesmo project_id usado para criar a transferência e ter todas as permissões necessárias.
  • PROJECT_ID: o ID do projeto do Trusted Cloud by S3NS . Se --project_id não for fornecido para especificar um projeto determinado, o projeto padrão será usado.
  • REGION: local da configuração de transferência.
  • LIST_OF_TABLES: uma lista de entidades a serem transferidas. Use uma especificação de nomenclatura hierárquica: database.table. Esse campo aceita expressões regulares RE2 para especificar tabelas. Exemplo:
    • db1..*: especifica todas as tabelas no banco de dados
    • db1.table1;db2.table2: uma lista de tabelas
  • AGENT_POOL_NAME: o nome do pool de agentes usado para criar agentes.
  • DATAPROC_METASTORE: o metastore do Dataproc de destino para destino OSS gerenciado. Para usar o BigLake Metastore, omita esse campo da configuração de transferência. Para mais informações sobre como usar o metastore do BigLake para migrar metadados, consulte Migração de metadados.

Execute este comando para criar a configuração de transferência e iniciar a transferência do data lake do HDFS. As transferências são programadas para serem executadas a cada 24 horas por padrão, mas podem ser configuradas com opções de programação de transferência.

Quando a transferência for concluída, suas tabelas no cluster do Hadoop serão migradas para MIGRATION_BUCKET.

Opções de ingestão de dados

As seções a seguir fornecem mais informações sobre como configurar suas transferências de data lake do HDFS.

Migração de metadados

Os metadados podem ser migrados para o metastore do Dataproc ou do BigLake, com os dados subjacentes armazenados no Cloud Storage.

Para transferir metadados para o metastore do Dataproc, especifique o URL do metastore no campo destination_dataproc_metastore.

Para transferir metadados para o metastore do BigLake, não é necessário especificar um campo destination_dataproc_metastore na configuração de transferência. O sistema determina automaticamente o conjunto de dados de destino do BigQuery no campo targetName dos arquivos de mapeamento YAML gerados. O campo targetName é formatado como um identificador de duas partes, por exemplo, bigquery_dataset_name.bigquery_table_name. Por padrão, a nomenclatura vai se alinhar ao sistema de origem. Verifique se o conjunto de dados do BigQuery com o nome do esquema de origem existe. Caso contrário, crie-o antes de executar a transferência.

Para usar outro conjunto de dados do BigQuery, forneça um arquivo YAML de configuração adicional (com o sufixo config.yaml) no DUMPER_BUCKET que contenha um conjunto de regras de reescrita de objetos e gere os mapeamentos de tradução. O exemplo a seguir é um conjunto de regras que mapeia o banco de dados de origem chamado my_hive_db para um conjunto de dados do BigQuery chamado my_bq_dataset:

relation:
  - match:
      schema: my_hive_db
    outputName:
      database: null
      schema: my_bq_dataset

O parâmetro schema precisa corresponder ao nome do conjunto de dados do BigQuery, e o parâmetro relation precisa corresponder ao nome da tabela. Para mais informações, consulte Mapeamento de nomes de saída.

O parâmetro database também precisa ser definido como null.

Transferências incrementais

Quando uma configuração de transferência é definida com uma programação recorrente, cada transferência subsequente atualiza a tabela no Trusted Cloud by S3NS com as atualizações mais recentes feitas na tabela de origem. Por exemplo, todas as operações de inserção, exclusão ou atualização com mudanças de esquema são refletidas em Trusted Cloud by S3NS com cada transferência.

Opções de programação de transferência

Por padrão, as transferências são programadas para ser executadas a cada 24 horas. Para configurar a frequência das transferências, adicione a flag --schedule à configuração de transferência e especifique uma programação usando a sintaxe schedule. As transferências do data lake do HDFS precisam ter um mínimo de 24 horas entre as execuções.

Para transferências únicas, adicione a flag end_time à configuração de transferência para executar a transferência apenas uma vez.

Monitorar transferências de data lake do HDFS

Depois de programar uma transferência de data lake do HDFS, é possível monitorar o job de transferência com comandos da ferramenta de linha de comando bq. Para informações sobre como monitorar seus jobs de transferência, consulte Ver suas transferências.

Acompanhar o status da migração de tabelas

Também é possível executar a ferramenta dwh-dts-status para monitorar o status de todas as tabelas transferidas em uma configuração de transferência ou um banco de dados específico. Também é possível usar a ferramenta dwh-dts-status para listar todas as configurações de transferência em um projeto.

Antes de começar

Antes de usar a ferramenta dwh-dts-status, faça o seguinte:

  1. Baixe o pacote dwh-migration-tool do repositório dwh-migration-tools do GitHub para ter a ferramenta dwh-dts-status.

  2. Autentique sua conta para Trusted Cloud by S3NS com o seguinte comando:

    gcloud auth application-default login

    Para mais informações, consulte Como as credenciais padrão do aplicativo funcionam.

  3. Verifique se o usuário tem os papéis bigquery.admin e logging.viewer. Para mais informações sobre papéis do IAM, consulte Referência de controle de acesso.

Listar todas as configurações de transferência em um projeto

Para listar todas as configurações de transferência em um projeto, use o seguinte comando:

  ./dwh-dts-status --list-transfer-configs --project-id=[PROJECT_ID] --location=[LOCATION]

Substitua:

  • PROJECT_ID : o ID do projeto Trusted Cloud by S3NS que está executando as transferências.
  • LOCATION : o local em que a configuração de transferência foi criada.

Esse comando gera uma tabela com uma lista de nomes e IDs de configurações de transferência.

Ver os status de todas as tabelas em uma configuração

Para conferir o status de todas as tabelas incluídas em uma configuração de transferência, use o comando a seguir:

  ./dwh-dts-status --list-status-for-config --project-id=[PROJECT_ID] --config-id=[CONFIG_ID] --location=[LOCATION]

Substitua:

  • PROJECT_ID: o ID do projeto Trusted Cloud by S3NS que está executando as transferências.
  • LOCATION: o local em que a configuração de transferência foi criada.
  • CONFIG_ID: o ID da configuração de transferência especificada.

Esse comando gera uma tabela com uma lista de tabelas e o status da transferência na configuração especificada. O status da transferência pode ser um dos seguintes valores: PENDING, RUNNING, SUCCEEDED, FAILED, CANCELLED.

Conferir os status de todas as tabelas em um banco de dados

Para conferir o status de todas as tabelas transferidas de um banco de dados específico, use o comando a seguir:

  ./dwh-dts-status --list-status-for-database --project-id=[PROJECT_ID] --database=[DATABASE]

Substitua:

  • PROJECT_ID: o ID do projeto Trusted Cloud by S3NS que está executando as transferências.
  • DATABASE:o nome do banco de dados especificado.

Esse comando gera uma tabela com uma lista de tabelas e o status da transferência delas no banco de dados especificado. O status da transferência pode ser um dos seguintes valores: PENDING, RUNNING, SUCCEEDED, FAILED, CANCELLED.