Esegui la migrazione dei metadati da Dataproc Metastore a Lakehouse

Questo documento spiega come 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, basato su Lakehouse senza confini.

Casi d'uso

  • Modernizzazione serverless: esegui la transizione da un Hive Metastore (HMS) convenzionale a un catalogo completamente gestito con scalabilità automatica, che elimina l'overhead operativo della gestione del metastore.
  • Collaborazione multi-motore: abilita la condivisione dei 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 duplicare i file.
  • Integrazione diretta di BigQuery: esegui query sulle tabelle open source direttamente da BigQuery con un'esecuzione ad alte prestazioni.
  • Governance unificata: consolida i metadati in un'unica fonte attendibile per semplificare l'individuazione dei dati e garantire l'applicazione coerente delle policy.
  • Formati di tabella moderni: adotta senza problemi formati aperti avanzati come Apache Iceberg mantenendo la piena compatibilità con i carichi di lavoro 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 o i percorsi Cloud Storage in cui risiedono i dati e i metadati della tabella di origine (ad esempio, il bucket del warehouse Dataproc Metastore, come gs://gcs-your-project-name-0825d7b3-0627-4637-8fd0-cc6271d00eb4/hive-warehouse).

    Se il catalogo di destinazione non include la località dei dati, la migrazione della tabella non riesce perché il catalogo di destinazione non può registrare le tabelle. Per la creazione del catalogo Iceberg, consulta Configurare l'endpoint del catalogo REST Iceberg.

    Per creare un catalogo Hive, consulta Creare un catalogo Hive Lakehouse.
  3. Accedi al tuo Google Cloud account. 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 carichi di lavoro.

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

  5. Enable the Lakehouse for Apache Iceberg, Dataproc Metastore APIs.

    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 for Apache Iceberg, Dataproc Metastore APIs.

    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:

  • Avvia la migrazione: Editor Dataproc Metastore (roles/metastore.editor)
  • Crea cataloghi Hive o Iceberg: Amministratore BigLake (roles/biglake.admin)
  • Esegui la migrazione dei metadati ai cataloghi di destinazione utilizzando un progetto di destinazione: Amministratore BigLake (roles/biglake.admin) sull'agente del servizio Dataproc Metastore (service-PROJECT_NUMBER@gcp-sa-metastore.iam.gserviceaccount.com).
  • Scrivi report di migrazione per il bucket dei report (se non utilizzi il bucket degli artefatti del servizio): Amministratore oggetti Storage (roles/storage.objectAdmin) sull'agente del 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

La procedura 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 gcloud beta metastore services migrations start comando o chiama il startMigration metodo sul servizio Dataproc Metastore per avviare la migrazione.
  3. Esegui il polling per lo stato: monitora l'avanzamento della migrazione utilizzando il gcloud beta metastore services migrations describe comando o eseguendo il polling dell' esecuzione di destinazione.
  4. Esamina i report: esamina i report JSON dettagliati scritti nel percorso Cloud Storage specificato per verificare i risultati.

Eseguire una migrazione

Per eseguire una migrazione, devi attivare la procedura di migrazione e poi monitorarne l'avanzamento.

Avviare la migrazione

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

gcloud

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

gcloud beta 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 Google Cloud ID progetto
  • 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 startMigration metodo con una BigLakeMetastoreMigrationConfig configurazione:

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/v1beta/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 Google Cloud ID progetto
  • 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

Eseguire il polling dell'esecuzione della migrazione

La richiesta avvia un'operazione a lunga esecuzione (LRO) e restituisce un ID di esecuzione della migrazione univoco. 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 gcloud beta metastore services migrations describe comando:

gcloud beta 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 get metodo sul percorso di esecuzione:

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

Sostituisci quanto segue:

  • PROJECT_ID: il tuo Google Cloud ID progetto
  • 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 di migrazione dettagliato

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

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

Limitazioni

  • Il catalogo di destinazione deve includere i bucket o i percorsi Cloud Storage in cui risiedono 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 della tabella 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 di nuovo la migrazione per sincronizzare il catalogo di destinazione con l'origine.
  • La migrazione è vincolata dalle limitazioni dei cataloghi di destinazione. Se una tabella Dataproc Metastore contiene una struttura o una proprietà dello schema non supportata dal catalogo di destinazione (ad esempio, tipi complessi), la migrazione per quella tabella specifica non riesce.
  • Le autorizzazioni di Dataproc Metastore per tabelle o database non vengono migrate a Lakehouse.

Passaggi successivi