Esegui la migrazione dei metadati da Dataproc Metastore a Lakehouse

Puoi eseguire la migrazione dei metadati da un servizio Dataproc Metastore a un endpoint del catalogo REST Apache Iceberg o a un endpoint del catalogo Hive, creato su Lakehouse senza confini. Questa migrazione ti aiuta a modernizzare i formati delle tabelle aperte e a unificare l'accesso al catalogo su più motori di analisi.

Casi d'uso

  • Modernizzazione serverless: passa da un Hive Metastore (HMS) convenzionale a un catalogo gestito con scalabilità automatica, che aiuta a eliminare l'overhead di gestione del metastore.
  • Collaborazione multimotore: condividi i dati tra i motori, tra cui Apache Spark, Apache Flink, Apache Hive e BigQuery, in modo che data scientist e analisti possano lavorare contemporaneamente sulle stesse tabelle senza duplicazione dei file.
  • Integrazione diretta di BigQuery: esegui query sulle tabelle open source direttamente da BigQuery.
  • Governance unificata: consolida i metadati in un'unica Single Source Of Truth per il rilevamento dei dati e l'applicazione coerente delle policy.
  • Formati di tabella moderni: adotta formati aperti come Apache Iceberg mantenendo la compatibilità con i workload Hive esistenti.

Prima di iniziare

  1. Assicurati che esista un servizio Dataproc Metastore attivo come origine della migrazione.
  2. Assicurati che il catalogo Hive o Iceberg di destinazione esista e includa i bucket Cloud Storage o i percorsi in cui si trovano i dati e i metadati della tabella di origine (ad esempio, il bucket warehouse di Dataproc Metastore, come gs://gcs-your-project-name-0825d7b3-0627-4637-8fd0-cc6271d00eb4/hive-warehouse).

    Se il catalogo di destinazione non include la posizione dei dati, la migrazione delle tabelle non riesce perché il catalogo di destinazione non può registrare le tabelle. Per la creazione del catalogo Iceberg, consulta Configura l'endpoint del catalogo REST Iceberg.

    Per creare un catalogo Hive, consulta Crea un catalogo Hive Lakehouse.
  3. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

  4. Verify that billing is enabled for your Google Cloud project.

  5. Enable the Lakehouse, Dataproc Metastore APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Lakehouse, Dataproc Metastore APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    8.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per attivare la migrazione, chiedi all'amministratore di concederti i seguenti ruoli IAM sul servizio Dataproc Metastore:

  • Avviare la migrazione: Dataproc Metastore Editor (roles/metastore.editor)
  • Creare cataloghi Hive o Iceberg: BigLake Admin (roles/biglake.admin)
  • Esegui la migrazione dei metadati ai cataloghi di destinazione utilizzando un progetto di destinazione: Amministratore BigLake (roles/biglake.admin) sull'agente di servizio Dataproc Metastore (service-PROJECT_NUMBER@gcp-sa-metastore.iam.gserviceaccount.com).
  • Scrittura di report sulla migrazione per il bucket di report (se non utilizzi il bucket degli artefatti del servizio): Amministratore oggetti Storage (roles/storage.objectAdmin) sull'agente di servizio Dataproc Metastore (service-PROJECT_NUMBER@gcp-sa-metastore.iam.gserviceaccount.com)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Come funziona una migrazione

Il processo di migrazione funziona nel seguente modo:

  1. Scegli il catalogo di destinazione: seleziona l'endpoint del catalogo Hive di destinazione o l'endpoint del catalogo REST Apache Iceberg per la migrazione.
  2. Attiva la migrazione: esegui il comando gcloud metastore services migrations start o chiama il metodo startMigration sul servizio Dataproc Metastore per avviare la migrazione.
  3. Polling dello stato: monitora l'avanzamento della migrazione utilizzando il comando gcloud metastore services migrations describe o eseguendo il polling dell'esecuzione di destinazione.
  4. Esamina i report Recensioni: esamina i report JSON dettagliati scritti nel percorso Cloud Storage specificato per verificare i risultati.

Eseguire una migrazione

Per eseguire una migrazione, devi attivare il processo di migrazione e poi monitorarne l'avanzamento.

Avvia la migrazione

Per attivare la migrazione dei metadati su un servizio Dataproc Metastore, utilizza la console Google Cloud , l'interfaccia a riga di comando gcloud o l'API REST.

Console

  1. Nella console Google Cloud , vai alla pagina Dataproc Metastore.

    Vai a Dataproc Metastore

  2. Nell'elenco dei servizi Metastore, fai clic sul nome del servizio di cui vuoi eseguire la migrazione.

  3. Nella pagina dei dettagli del servizio, fai clic su Esegui la migrazione a Lakehouse nella barra di navigazione in alto.

  4. In Nome migrazione, inserisci un nome visualizzato per la migrazione.

  5. Per Tipo di migrazione, seleziona Migrazione di backfill per eseguire la migrazione o Dry run per convalidare la migrazione senza scrivere i metadati nel catalogo di destinazione.

  6. Configura le impostazioni di destinazione:

    • Report: (facoltativo) seleziona il percorso di Cloud Storage per salvare il report sullo stato della migrazione. Se non specificato, il report viene generato nel bucket degli artefatti del servizio Dataproc Metastore.
    • Gestione dei conflitti: seleziona se vuoi saltare o sovrascrivere le voci di database duplicate.

  7. In Destinazione, seleziona i tipi di catalogo verso cui vuoi eseguire la migrazione, Endpoint del catalogo REST Iceberg o Metastore Hive. Puoi eseguire la migrazione a un catalogo o a entrambi i cataloghi contemporaneamente, a seconda del tipo di tabelle di cui devi eseguire la migrazione dal database di origine.

    Se esegui la migrazione al catalogo REST Iceberg:

    1. In Progetto, seleziona il progetto che contiene il catalogo di cui vuoi eseguire la migrazione.
    2. In Catalogo REST Iceberg, seleziona il catalogo in cui vuoi eseguire la migrazione o fai clic su Crea catalogo per crearne uno nuovo.

    Se esegui la migrazione al catalogo Hive:

    1. In Progetto, seleziona il progetto che contiene il catalogo di cui vuoi eseguire la migrazione.
    2. Per Catalogo Hive, seleziona il catalogo in cui vuoi eseguire la migrazione o fai clic su Crea catalogo per crearne uno nuovo.

  8. Fai clic su Avvia migrazione.

Viene visualizzata automaticamente la scheda Migrazioni. In Migrazioni gestite, la migrazione viene elencata e lo stato continua ad aggiornarsi fino al termine della migrazione.

gcloud

Per avviare la migrazione utilizzando gcloud, esegui il comando gcloud metastore services migrations start:

gcloud metastore services migrations start SERVICE_ID \
    --location=REGION \
    --hive-catalog="projects/PROJECT_ID/catalogs/HIVE_CATALOG_ID" \
    --hive-databases="HIVE_DB_1,HIVE_DB_2" \
    --iceberg-catalog="projects/PROJECT_ID/catalogs/ICEBERG_CATALOG_ID" \
    --iceberg-namespaces="ICEBERG_NAMESPACE_1,ICEBERG_NAMESPACE_2" \
    --async

Sostituisci quanto segue:

  • SERVICE_ID: l'ID del servizio Dataproc Metastore
  • REGION: la regione del servizio Dataproc Metastore
  • PROJECT_ID: il tuo ID progetto Google Cloud
  • HIVE_CATALOG_ID: l'ID del catalogo Hive di destinazione
  • HIVE_DB_1, HIVE_DB_2: i database Hive di cui eseguire la migrazione.
  • ICEBERG_CATALOG_ID: l'ID del catalogo Iceberg di destinazione
  • ICEBERG_NAMESPACE_1, ICEBERG_NAMESPACE_2: gli spazi dei nomi Iceberg di cui eseguire la migrazione.

REST

Per attivare la migrazione dei metadati utilizzando l'API REST, chiama il metodo startMigration con una configurazione BigLakeMetastoreMigrationConfig:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "migrationExecution": {
        "biglakeMetastoreMigrationConfig": {
          "mode": "BACKFILL",
          "dryRun": false,
          "reportPath": "gs://BUCKET_NAME/PATH/",
          "conflictPolicy": "SKIP",
          "hiveConfig": {
            "catalog": "projects/PROJECT_ID/catalogs/HIVE_CATALOG_ID",
            "databases": ["HIVE_DB_1", "HIVE_DB_2"]
          },
          "icebergConfig": {
            "catalog": "projects/PROJECT_ID/catalogs/ICEBERG_CATALOG_ID",
            "namespaces": ["ICEBERG_NAMESPACE_1", "ICEBERG_NAMESPACE_2"]
          }
        }
      }
    }' \
    "https://metastore.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/services/SERVICE_ID:startMigration"

Sostituisci quanto segue:

  • BUCKET_NAME: il nome del bucket Cloud Storage per i report
  • PATH: il percorso nel bucket per i report
  • PROJECT_ID: il tuo ID progetto Google Cloud
  • HIVE_CATALOG_ID: l'ID del catalogo Hive di destinazione
  • HIVE_DB_1, HIVE_DB_2: i database Hive di cui eseguire la migrazione.
  • ICEBERG_CATALOG_ID: l'ID del catalogo Iceberg di destinazione
  • ICEBERG_NAMESPACE_1, ICEBERG_NAMESPACE_2: gli spazi dei nomi Iceberg di cui eseguire la migrazione.
  • REGION: la regione del servizio Dataproc Metastore
  • SERVICE_ID: l'ID del servizio Dataproc Metastore

Esegui il polling dell'esecuzione della migrazione

La richiesta avvia un'operazione a lunga esecuzione (LRO) e restituisce un ID univoco di esecuzione della migrazione. Puoi monitorare l'avanzamento dell'esecuzione utilizzando l'interfaccia a riga di comando gcloud o l'API REST:

gcloud

Per descrivere l'esecuzione della migrazione utilizzando gcloud, esegui il comando gcloud metastore services migrations describe:

gcloud metastore services migrations describe MIGRATION_EXECUTION_ID \
    --service=SERVICE_ID \
    --location=REGION

Sostituisci quanto segue:

  • MIGRATION_EXECUTION_ID: l'ID dell'esecuzione della migrazione restituito nel passaggio precedente
  • SERVICE_ID: l'ID del servizio Dataproc Metastore
  • REGION: la regione del servizio Dataproc Metastore

REST

Per monitorare l'avanzamento dell'esecuzione utilizzando l'API REST, chiama il metodo get su questo percorso di esecuzione:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://metastore.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/services/SERVICE_ID/migrationExecutions/MIGRATION_EXECUTION_ID"

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud
  • REGION: la regione del servizio Dataproc Metastore
  • SERVICE_ID: l'ID del servizio Dataproc Metastore
  • MIGRATION_EXECUTION_ID: l'ID dell'esecuzione della migrazione restituito nel passaggio precedente

Report dettagliato sulla migrazione

Al termine della migrazione (backfill o dry run), lo strumento di migrazione scrive due file di report JSON dettagliati basati sullo schema MigrationReport nel percorso Cloud Storage di destinazione specificato in reportPath:

  • summary.json: contiene la struttura MigrationSummary aggregata di alto livello.
  • full_report.json: contiene un report sulla migrazione dettagliato e più granulare. Per saperne di più, consulta CatalogReport.

Per visualizzare il report nella console Google Cloud , segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina Dataproc Metastore.

    Vai a Dataproc Metastore

  2. Nell'elenco dei servizi metastore, fai clic sul nome visualizzato del servizio che contiene il report.

    Viene visualizzata la pagina Migrazioni.

  3. In Migrazioni gestite, seleziona il nome della migrazione che contiene il report.

    Viene visualizzata la pagina Dettagli migrazione, che mostra i dettagli dei database e delle tabelle di cui è stata eseguita la migrazione e lo stato della migrazione.

Limitazioni

  • Il catalogo di destinazione deve includere i bucket Cloud Storage o i percorsi in cui si trovano i dati e i metadati della tabella di origine (ad esempio il bucket del warehouse Dataproc Metastore). Se il catalogo di destinazione non è configurato con la località del bucket di dati, il catalogo di destinazione non può registrare le tabelle e la migrazione delle tabelle non riesce.
  • Lo strumento supporta solo un backfill una tantum. Eventuali modifiche ai metadati di Dataproc Metastore di origine dopo la migrazione non vengono propagate automaticamente. Devi eseguire nuovamente la migrazione per sincronizzare il catalogo di destinazione con l'origine.
  • La migrazione è soggetta alle limitazioni dei cataloghi di destinazione. Se una tabella Dataproc Metastore contiene una struttura di schema o una proprietà non supportata dal catalogo di destinazione (ad esempio tipi complessi), la migrazione per quella tabella specifica non va a buon fine.
  • Le autorizzazioni di Dataproc Metastore per tabelle o database non vengono migrate in Lakehouse.

Passaggi successivi