Esegui la migrazione delle tabelle da un data lake HDFS

Questo documento mostra come eseguire la migrazione delle tabelle del data lake Apache Hadoop Distributed File System (HDFS) a Trusted Cloud.

Puoi utilizzare il connettore di migrazione del data lake HDFS in BigQuery Data Transfer Service per eseguire la migrazione delle tabelle Hive e Iceberg da varie distribuzioni Hadoop, sia on-premise che in ambienti cloud, in Trusted Cloud.

Con il connettore del data lake HDFS, puoi registrare le tabelle del data lake HDFS sia con Dataproc Metastore che con BigLake Metastore utilizzando Cloud Storage come spazio di archiviazione sottostante per i tuoi file.

Il seguente diagramma fornisce una panoramica della procedura di migrazione delle tabelle dal cluster Hadoop.

Panoramica della migrazione delle tabelle dal data lake Hive a BigQuery.

Limitazioni

I trasferimenti del data lake HDFS sono soggetti alle seguenti limitazioni:

  • Per eseguire la migrazione delle tabelle Iceberg, devi registrarle con il metastore BigLake per consentire l'accesso in scrittura per i motori open source (come Spark o Flink) e l'accesso in lettura per BigQuery.
  • Per eseguire la migrazione delle tabelle Hive, devi registrarle con Dataproc Metastore per consentire l'accesso in scrittura per i motori open source e l'accesso in lettura per BigQuery.
  • Devi utilizzare lo strumento a riga di comando bq per eseguire la migrazione di una tabella del data lake HDFS a BigQuery.

Prima di iniziare

Prima di pianificare un trasferimento del data lake HDFS, devi eseguire le seguenti operazioni:

Crea un bucket Cloud Storage per i file migrati

Crea un bucket Cloud Storage che sarà la destinazione dei file del data lake di cui è stata eseguita la migrazione. Questo bucket è indicato in questo documento come MIGRATION_BUCKET.

File richiesti

Prima di poter pianificare un trasferimento del data lake HDFS, devi disporre dei seguenti file di migrazione in un bucket Cloud Storage:

  • Il file di metadati estratto (hive-dumper-output.zip)
  • Il file YAML di configurazione della traduzione (*.config.yaml)
  • I file YAML di mapping delle tabelle

Le sezioni seguenti descrivono come creare questi file.

hive-dumper-output.zip

Esegui lo strumento dwh-migration-dumper per estrarre i metadati per Apache Hive. Lo strumento genera un file denominato hive-dumper-output.zip in un bucket Cloud Storage, indicato in questo documento come DUMPER_BUCKET.

File YAML di configurazione della traduzione

Crea un file YAML di configurazione della traduzione con un nome contenente il suffisso .config.yaml, ad esempio translation.config.yaml, e caricalo nello stesso bucket che contiene hive-dumper-output.zip. Configura il file YAML di configurazione della traduzione per mappare i percorsi HDFS alle cartelle gestite di Cloud Storage, in modo simile all'esempio seguente:

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

Sostituisci MIGRATION_BUCKET con il nome del bucket Cloud Storage che è la destinazione dei file di cui è stata eseguita la migrazione.

Il campo location_expression è un'espressione Common Expression Language (CEL).

Per ulteriori informazioni su questo file YAML di configurazione, consulta Linee guida per creare un file YAML di configurazione.

Genera file YAML di mappatura delle tabelle

Per generare un file YAML di mappatura delle tabelle, esegui questo 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

Sostituisci quanto segue:

  • TRANSLATION_OUTPUT_BUCKET: l'URI di base di un bucket Cloud Storage che contiene il file YAML di mapping delle tabelle. Ad esempio, gs://output_bucket/tables/.
  • DUMPER_BUCKET: l'URI di base per il bucket Cloud Storage che contiene il file YAML di hive-dumper-output.zip e di configurazione.
  • TOKEN: il token OAuth. Puoi generarlo nella riga di comando con il comando gcloud auth print-access-token.
  • PROJECT_ID: il progetto in cui elaborare la traduzione.
  • LOCATION: la località in cui viene elaborato il job. Ad esempio, eu o us.

Quando viene eseguita, l'API Translation Service restituisce un WORKFLOW_ID e avvia un job asincrono in background. Puoi monitorare lo stato di questo job utilizzando il seguente comando:

  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

Al termine, vengono creati i file YAML di mappatura delle tabelle. I file YAML di mappatura delle tabelle potrebbero essere costituiti da più file di mappatura, uno per ogni tabella, archiviati nella cartella Cloud Storage.

Abilita API

Abilita le seguenti API nel tuo progetto Trusted Cloud :

  • API Data Transfer
  • API Storage Transfer

Un agente di servizio viene creato quando abiliti l'API Data Transfer.

Configura autorizzazioni

  1. Crea un account di servizio e concedigli il ruolo Amministratore BigQuery (roles/bigquery.admin). Questo account di servizio viene utilizzato per creare la configurazione del trasferimento.
  2. Quando viene abilitata l'API Data Transfer, viene creato un agente di servizio (P4SA). Concedi i seguenti ruoli:
    • roles/metastore.metadataOwner
    • roles/storagetransfer.admin
    • roles/serviceusage.serviceUsageConsumer
    • roles/storage.objectViewer
      • Se esegui la migrazione dei metadati per le tabelle BigLake Iceberg, concedi i ruoli roles/storage.objectAdmin e roles/bigquery.admin anziché roles/storage.objectViewer.

  3. Concedi all'agente di servizio il ruolo roles/iam.serviceAccountTokenCreator con il seguente 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

Configura Storage Transfer Agent

Per configurare l'agente di trasferimento dello spazio di archiviazione richiesto per un trasferimento del data lake HDFS:

  1. Configura le autorizzazioni per eseguire l'agente di trasferimento dello spazio di archiviazione sul tuo cluster Hadoop.
  2. Installa Docker sulle macchine agenti on-premise.
  3. Crea un pool di agenti Storage Transfer Service nel tuo progetto Trusted Cloud by S3NS .
  4. Installa gli agenti sulle macchine agenti on-premise.

Pianifica un trasferimento del data lake HDFS

Per pianificare un trasferimento del data lake HDFS, inserisci il comando bq mk e fornisci il flag di creazione del trasferimento --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"}'

Sostituisci quanto segue:

  • TRANSFER_NAME: il nome visualizzato per la configurazione del trasferimento. Il nome del trasferimento può essere qualsiasi valore che ti consenta di identificare il trasferimento se devi modificarlo in un secondo momento.
  • SERVICE_ACCOUNT: il nome del account di servizio utilizzato per autenticare il trasferimento. Il account di servizio deve essere di proprietà dello stesso project_id utilizzato per creare il trasferimento e deve disporre di tutte le autorizzazioni richieste.
  • PROJECT_ID: il tuo ID progetto Trusted Cloud by S3NS . Se --project_id non viene fornito per specificare un progetto particolare, viene utilizzato il progetto predefinito.
  • REGION: la posizione di questa configurazione di trasferimento.
  • LIST_OF_TABLES: un elenco di entità da trasferire. Utilizza una specifica di denominazione gerarchica: database.table. Questo campo supporta l'espressione regolare RE2 per specificare le tabelle. Ad esempio:
    • db1..*: specifica tutte le tabelle nel database
    • db1.table1;db2.table2: un elenco di tabelle
  • AGENT_POOL_NAME: il nome del pool di agenti utilizzato per la creazione degli agenti.
  • DATAPROC_METASTORE: il Dataproc Metastore di destinazione per la destinazione OSS gestita. Per utilizzare BigLake Metastore, puoi omettere questo campo dalla configurazione di trasferimento. Per ulteriori informazioni sull'utilizzo di BigLake Metastore per eseguire la migrazione dei metadati, vedi Migrazione dei metadati.

Esegui questo comando per creare la configurazione del trasferimento e avviare il trasferimento del data lake HDFS. Per impostazione predefinita, i trasferimenti vengono eseguiti ogni 24 ore, ma possono essere configurati con le opzioni di pianificazione del trasferimento.

Al termine del trasferimento, le tabelle nel cluster Hadoop verranno migrate a MIGRATION_BUCKET.

Opzioni di importazione dei dati

Le sezioni seguenti forniscono ulteriori informazioni su come configurare i trasferimenti del data lake HDFS.

Migrazione dei metadati

I metadati possono essere migrati a Dataproc Metastore o BigLake Metastore con i dati sottostanti archiviati in Cloud Storage.

Per trasferire i metadati a Dataproc Metastore, specifica l'URL del metastore nel campo destination_dataproc_metastore.

Per trasferire i metadati a BigLake Metastore, non è necessario specificare un campo destination_dataproc_metastore nella configurazione del trasferimento. Il sistema determina automaticamente il set di dati BigQuery di destinazione dal campo targetName all'interno dei file di mapping YAML generati. Il campo targetName è formattato come un identificatore in due parti, ad esempio bigquery_dataset_name.bigquery_table_name. Per impostazione predefinita, la denominazione sarà allineata al sistema di origine. Devi assicurarti che esista il set di dati BigQuery con il nome dello schema di origine oppure crearlo prima di eseguire il trasferimento.

Per utilizzare un altro set di dati BigQuery, devi fornire un file YAML di configurazione aggiuntivo (con suffisso config.yaml) in DUMPER_BUCKET contenente un set di regole di riscrittura degli oggetti e poi generare i mapping di traduzione. L'esempio seguente è un insieme di regole che mappa il database di origine denominato my_hive_db a un set di dati BigQuery denominato my_bq_dataset:

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

Il parametro schema deve corrispondere al nome del set di dati BigQuery e il parametro relation deve corrispondere al nome della tabella. Per saperne di più, vedi Mapping dei nomi di output.

Anche il parametro database deve essere impostato su null.

Trasferimenti incrementali

Quando una configurazione del trasferimento viene impostata con una pianificazione ricorrente, ogni trasferimento successivo aggiorna la tabella su Trusted Cloud by S3NS con gli ultimi aggiornamenti apportati alla tabella di origine. Ad esempio, tutte le operazioni di inserimento, eliminazione o aggiornamento con modifiche allo schema vengono riflesse in Trusted Cloud by S3NS a ogni trasferimento.

Opzioni di pianificazione del trasferimento

Per impostazione predefinita, i trasferimenti sono pianificati per essere eseguiti ogni 24 ore. Per configurare la frequenza di esecuzione dei trasferimenti, aggiungi il flag --schedule alla configurazione del trasferimento e specifica una pianificazione del trasferimento utilizzando la sintassi schedule. I trasferimenti del data lake HDFS devono avere un intervallo minimo di 24 ore tra le esecuzioni del trasferimento.

Per i trasferimenti una tantum, puoi aggiungere il flag end_time alla configurazione del trasferimento per eseguire il trasferimento una sola volta.

Monitorare i trasferimenti del data lake HDFS

Dopo aver pianificato un trasferimento del data lake HDFS, puoi monitorare il job di trasferimento con i comandi dello strumento a riga di comando bq. Per informazioni sul monitoraggio dei job di trasferimento, vedi Visualizzare i trasferimenti.

Monitorare lo stato della migrazione delle tabelle

Puoi anche eseguire lo strumento dwh-dts-status per monitorare lo stato di tutte le tabelle trasferite all'interno di una configurazione di trasferimento o di un database specifico. Puoi anche utilizzare lo strumento dwh-dts-status per elencare tutte le configurazioni di trasferimento in un progetto.

Prima di iniziare

Prima di poter utilizzare lo strumento dwh-dts-status, segui questi passaggi:

  1. Scarica lo strumento dwh-dts-status scaricando il pacchetto dwh-migration-tool dal repository GitHub dwh-migration-tools.

  2. Autentica il tuo account su Trusted Cloud by S3NS con questo comando:

    gcloud auth application-default login

    Per saperne di più, consulta Come funzionano le credenziali predefinite dell'applicazione.

  3. Verifica che l'utente disponga del ruolo bigquery.admin e logging.viewer. Per maggiori informazioni sui ruoli IAM, consulta Riferimento al controllo dell'accesso.

Elenco di tutte le configurazioni di trasferimento in un progetto

Per elencare tutte le configurazioni di trasferimento in un progetto, utilizza il seguente comando:

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

Sostituisci quanto segue:

  • PROJECT_ID : l'ID progetto Trusted Cloud by S3NS che esegue i trasferimenti.
  • LOCATION : la località in cui è stata creata la configurazione del trasferimento.

Questo comando restituisce una tabella con un elenco di nomi e ID di configurazione del trasferimento.

Visualizza gli stati di tutte le tabelle in una configurazione

Per visualizzare lo stato di tutte le tabelle incluse in una configurazione di trasferimento, utilizza il seguente comando:

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

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto Trusted Cloud by S3NS che esegue i trasferimenti.
  • LOCATION: la località in cui è stata creata la configurazione del trasferimento.
  • CONFIG_ID: l'ID della configurazione di trasferimento specificata.

Questo comando restituisce una tabella con un elenco di tabelle e il relativo stato di trasferimento nella configurazione di trasferimento specificata. Lo stato del trasferimento può essere uno dei seguenti valori: PENDING, RUNNING, SUCCEEDED, FAILED, CANCELLED.

Visualizzare gli stati di tutte le tabelle di un database

Per visualizzare lo stato di tutte le tabelle trasferite da un database specifico, utilizza il seguente comando:

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

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto Trusted Cloud by S3NS che esegue i trasferimenti.
  • DATABASE:il nome del database specificato.

Questo comando restituisce una tabella con un elenco di tabelle e il relativo stato di trasferimento nel database specificato. Lo stato del trasferimento può essere uno dei seguenti valori: PENDING, RUNNING, SUCCEEDED, FAILED, CANCELLED.