将元数据从 Dataproc Metastore 迁移到 Lakehouse

本文档介绍了如何将元数据从 Dataproc Metastore 服务迁移到基于 无边界 Lakehouse 构建的 Apache Iceberg REST 目录端点或 Hive 目录端点。

使用场景

  • 无服务器现代化：从传统的 Hive Metastore (HMS) 迁移到自动伸缩的全代管式目录，从而消除元存储区管理运营开销。
  • 多引擎协作： 实现跨引擎（包括 Apache Spark、Apache Flink、Apache Hive 和 BigQuery）的数据共享，以便数据科学家和分析师可以同时处理同一张表，而无需重复文件。
  • 直接集成 BigQuery： 直接从 BigQuery 查询开源表，并以高性能执行。
  • 统一治理： 将元数据整合到单一可信来源中，以简化数据发现并实现一致的政策执行。
  • 现代表格式： 无缝采用 Apache Iceberg 等高级开放格式，同时与现有 Hive 工作负载保持完全兼容。

准备工作

  1. 确保存在一个活跃的 Dataproc Metastore 服务作为迁移来源。
  2. 确保目标 Hive 目录或 Iceberg 目录存在，并且 包含源表数据和元数据所在的 Cloud Storage 存储桶或路径（例如 Dataproc Metastore 仓库存储桶，如 gs://gcs-your-project-name-0825d7b3-0627-4637-8fd0-cc6271d00eb4/hive-warehouse）。

    如果目标目录不包含数据位置，则表 迁移会失败，因为目标目录无法注册表。如需创建 Iceberg 目录，请参阅设置 Iceberg REST 目录端点。

    如需创建 Hive 目录，请参阅 创建 Lakehouse Hive 目录。
  3. 登录您的 Google Cloud 账号。如果您是新手 Google Cloud， 请创建一个账号来评估我们的产品在 实际场景中的表现。新客户还可获享 $300 赠金，用于 运行、测试和部署工作负载。

  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.

所需的角色

如需获得触发迁移所需的权限，请让您的管理员向您授予 Dataproc Metastore 服务的以下 IAM 角色：

  • 启动迁移： Dataproc Metastore Editor (roles/metastore.editor)
  • 创建 Hive 或 Iceberg 目录： BigLake Admin (roles/biglake.admin)
  • 使用目标项目将元数据迁移到目标目录： Dataproc Metastore 服务代理 (service-PROJECT_NUMBER@gcp-sa-metastore.iam.gserviceaccount.com) 的 BigLake Admin (roles/biglake.admin)。
  • 为报告存储桶编写迁移报告（如果未使用服务工件存储桶）： Dataproc Metastore 服务代理 (service-PROJECT_NUMBER@gcp-sa-metastore.iam.gserviceaccount.com) 的 Storage Object Admin (roles/storage.objectAdmin)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义 角色或其他预定义 角色来获取所需的权限。

迁移的工作原理

迁移过程的工作原理如下：

  1. 选择目标目录：为迁移选择目标 Hive 目录端点 或 Apache Iceberg REST 目录端点。
  2. 触发迁移：运行 gcloud beta metastore services migrations start 命令或对 Dataproc Metastore 服务调用 startMigration 方法，以启动 迁移。
  3. 轮询状态：使用 gcloud beta metastore services migrations describe 命令或通过轮询 目标执行来监控迁移进度。
  4. 查看报告：查看写入 指定 Cloud Storage 路径的详细 JSON 报告，以验证结果。

运行迁移

如需运行迁移，请触发迁移过程，然后监控其进度。

开始迁移

如需在 Dataproc Metastore 服务上触发元数据迁移，请使用 gcloud CLI 或 REST API。

gcloud

如需使用 gcloud 启动迁移，请运行 gcloud beta metastore services migrations start 命令：

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

替换以下内容：

  • SERVICE_ID：Dataproc Metastore 服务的 ID
  • REGION：Dataproc Metastore 服务的区域
  • PROJECT_ID：您的 Google Cloud 项目 ID
  • HIVE_CATALOG_ID：目标 Hive 目录 ID
  • HIVE_DB_1、HIVE_DB_2：要迁移的 Hive 数据库。
  • ICEBERG_CATALOG_ID：目标 Iceberg 目录 ID
  • ICEBERG_NAMESPACE_1、ICEBERG_NAMESPACE_2：要迁移的 Iceberg 命名空间。

REST

如需使用 REST API 触发元数据迁移，请使用 BigLakeMetastoreMigrationConfig 配置调用 startMigration 方法：

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"

替换以下内容：

  • BUCKET_NAME：用于报告的 Cloud Storage 存储桶的名称
  • PATH：存储桶中用于报告的路径
  • PROJECT_ID：您的 Google Cloud 项目 ID
  • HIVE_CATALOG_ID：目标 Hive 目录 ID
  • HIVE_DB_1、HIVE_DB_2：要迁移的 Hive 数据库。
  • ICEBERG_CATALOG_ID：目标 Iceberg 目录 ID
  • ICEBERG_NAMESPACE_1、ICEBERG_NAMESPACE_2：要迁移的 Iceberg 命名空间。
  • REGION：Dataproc Metastore 服务的区域
  • SERVICE_ID：Dataproc Metastore 服务的 ID

轮询迁移执行

该请求会启动一项长时间运行 的操作 (LRO)，并返回唯一的迁移执行 ID。您可以使用 gcloud CLI 或 REST API 监控运行进度：

gcloud

如需使用 gcloud 描述迁移执行，请运行 gcloud beta metastore services migrations describe 命令：

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

替换以下内容：

  • MIGRATION_EXECUTION_ID：在上一步中返回的迁移执行 ID
  • SERVICE_ID：Dataproc Metastore 服务的 ID
  • REGION：Dataproc Metastore 服务的区域

REST

如需使用 REST API 监控运行进度，请对该执行路径调用 get 方法：

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"

替换以下内容：

  • PROJECT_ID：您的 Google Cloud 项目 ID
  • REGION：Dataproc Metastore 服务的区域
  • SERVICE_ID：Dataproc Metastore 服务的 ID
  • MIGRATION_EXECUTION_ID：在上一步中返回的迁移执行 ID

详细的迁移报告

迁移（回填或试运行）完成后，迁移工具会根据 MigrationReport 架构将 两个详细的 JSON 报告文件写入 reportPath 中指定的目标 Cloud Storage 路径：

  • summary.json：包含高级汇总的 MigrationSummary 结构。
  • full_report.json：包含详细、更精细的迁移报告。如需了解详情，请参阅 CatalogReport。

限制

  • 目标目录必须包含源表数据和元数据所在的 Cloud Storage 存储桶或 路径（例如 Dataproc Metastore 仓库存储桶）。 如果未为目标目录配置数据存储桶位置，则目标目录无法注册表，并且表迁移会失败。
  • 该工具仅支持一次性回填。迁移后对源 Dataproc Metastore 所做的任何元数据更改都不会自动传播。您必须重新运行迁移，才能将目标目录与来源同步。
  • 迁移受目标目录的限制。如果 Dataproc Metastore 表包含目标目录不支持的架构结构或属性（例如复杂类型），则该特定表的迁移会失败。
  • 表或数据库的 Dataproc Metastore 权限不会迁移到 Lakehouse。

后续步骤