将元数据从 Dataproc Metastore 迁移到 Lakehouse

您可以将元数据从 Dataproc Metastore 服务迁移到基于无边界 Lakehouse 构建的 Apache Iceberg REST 目录端点或 Hive 目录端点。此迁移有助于您实现现代化改造，采用开放式表格式，并统一跨多个分析引擎的目录访问。

使用场景

• 无服务器现代化改造：从传统 Hive Metastore (HMS) 转换为自动伸缩的托管式目录，这有助于消除 Metastore 管理开销。
• 多引擎协作：在多个引擎（包括 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 目录。
登录您的 Google Cloud 账号。如果您是 Google Cloud新手，请 创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

Verify that billing is enabled for your Google Cloud project.

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

Verify that billing is enabled for your Google Cloud project.

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

所需的角色

如需获得触发迁移所需的权限，请让管理员向您授予 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 metastore services migrations start 命令或在 Dataproc Metastore 服务上调用 startMigration 方法以启动迁移。
3. 轮询状态：使用 gcloud metastore services migrations describe 命令或通过轮询目标执行来监控迁移进度。
4. 评价报告：查看写入指定 Cloud Storage 路径的详细 JSON 报告，以验证结果。

运行迁移

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

开始迁移

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

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

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"

轮询迁移执行任务

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

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

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"

详细迁移报告

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

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

如需在 Google Cloud 控制台中查看报告，请按以下步骤操作：

1. 在 Google Cloud 控制台中，前往 Dataproc Metastore 页面。

   转到 Dataproc Metastore

2. 在 Metastore 服务列表中，点击包含报告的服务的显示名称。

   迁移页面会打开。

3. 在代管式迁移下，选择包含报告的迁移的名称。

   系统会打开迁移详情页面，其中显示有关已迁移数据库和表及其迁移状态的详细信息。

限制

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

后续步骤

• 详细了解 Lakehouse 运行时目录。
• 了解如何使用 Lakehouse 运行时目录设置 Spark 和 Hive。
• 了解如何使用 Lakehouse 运行时目录、Spark 和 BigQuery 查询 Iceberg 表。