将元数据从外部 Data Catalog 迁移到 Lakehouse REST catalog tables for Apache Iceberg

本文档介绍了如何将元数据从外部 Data Catalog 迁移到 Lakehouse REST catalog tables for Apache Iceberg。BigQuery Migration Service 支持从以下外部元存储迁移元数据：

  • Apache Hive Metastore
  • Apache Iceberg REST Catalog

限制

  • 从外部 Data Catalog 到 Lakehouse REST 目录表（适用于 Apache Iceberg）的元数据迁移是一次性同步。此功能不支持持续或定期同步，因此在迁移后进行的任何写入操作都无法显示，除非您再次迁移。
  • 不支持嵌套命名空间。
  • Iceberg REST 目录仅支持 Parquet 数据文件。
  • 无边界湖仓一体不支持 Apache Iceberg V3 表。
  • 从外部 Data Catalog 到 Lakehouse REST 目录表（适用于 Apache Iceberg）的元数据迁移仅支持最多 10,000 个表的迁移。如果您的工作负载需要处理超过 10,000 个表，我们建议您将工作负载拆分为多个迁移。
  • 从外部 Data Catalog 到 Lakehouse REST 目录表（适用于 Apache Iceberg）的元数据迁移不支持使用组织政策来强制执行网域限制共享。

准备工作

您必须先完成以下各部分中的步骤，然后才能从外部 Data Catalog 迁移元数据。

启用 API

启用 BigLake、BigQuery Data Transfer、BigQuery Migration、Secret Manager、Storage Transfer API（如果尚未启用）。

启用 API 所需的角色

如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

启用 API

启用 Data Transfer API 后，系统会创建一个服务代理。

配置权限

  1. 应向创建转移作业的用户或服务账号授予 BigQuery Admin 角色 (roles/bigquery.admin)。如果您使用服务账号，则该账号仅用于创建转移作业。

  2. 启用数据传输 API 后，系统会创建一个服务代理 (P4SA)。

    如需确保服务代理具有运行 Hive Metastore 转移作业所需的权限，请让管理员为服务代理授予项目的以下 IAM 角色：

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

    您的管理员还可以通过自定义角色或其他预定义角色向服务代理授予所需的权限。

  3. 如果您使用的是服务账号，请使用以下命令向服务代理授予 roles/iam.serviceAccountTokenCreator 角色：

    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

  4. 向 Storage Transfer Service 服务代理 (project-PROJECT_NUMBER@storage-transfer-service.s3ns-system.iam.gserviceaccount.com) 授予项目中的以下角色：

    • roles/storage.admin
    • 如果您要从本地或 HDFS 迁移，则还必须授予 roles/storagetransfer.serviceAgent 角色。

    您还可以配置更精细的权限。如需了解详情，请参阅以下指南：

所需的用户角色和权限

如需确保服务代理拥有创建、修改和运行 Lakehouse REST 目录表以进行 Apache Iceberg 迁移所需的权限，请让您的管理员为服务代理授予用户的以下 IAM 角色：

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

您的管理员还可以通过自定义角色或其他预定义角色向服务代理授予所需的权限。

所需的服务账号角色和权限

为确保客户提供的服务账号具有创建、修改和运行 Lakehouse REST 目录表以进行 Apache Iceberg 迁移所需的权限，请让您的管理员为客户提供的服务账号授予以下 IAM 角色：

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

您的管理员还可以通过自定义角色或其他预定义角色向客户提供的服务账号授予所需的权限。

您还必须为 BigQuery Migration Service 创建服务身份，并向其授予 roles/iam.serviceAccountTokenCreator 角色。

如需创建服务身份，请运行以下命令：

gcloud beta services identity create --service=bigquerymigration.googleapis.com --project=PROJECT_ID

如需向服务代理授予该角色，请运行以下命令：

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT --member serviceAccount:service-PROJECT_NUMBER@gcp-sa-bqms.s3ns-system.iam.gserviceaccount.com --role roles/iam.serviceAccountTokenCreator --project PROJECT_ID

替换以下内容：

  • SERVICE_ACCOUNT：客户提供的服务账号的 ID
  • PROJECT_ID：项目 ID
  • PROJECT_NUMBER：项目编号

配置 Secret

如果您要迁移到 Apache Iceberg REST 目录，则必须创建密钥来授权迁移。Secret 必须采用以下格式：

{
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "polaris_realm": "POLARIS_REALM",
  "scope": "SCOPE"
}

替换以下内容：

  • CLIENT_ID：OAuth 2.0 客户端 ID
  • CLIENT_SECRET：OAuth 2.0 客户端密钥
  • POLARIS_REALM：Polaris 目录的领域。只有 Apache Polaris 需要此字段。例如 FINANCE。
  • SCOPE：（可选）OAuth 2.0 范围。默认值为 PRINCIPAL_ROLE:ALL。

创建 Lakehouse 目录

创建 Lakehouse 目录。 迁移的元数据存储在您创建目录时指定的 Cloud Storage 存储桶中。

迁移元数据

如需开始将元数据迁移到 Lakehouse Iceberg REST 目录表，请执行以下操作：

  1. 在 Cloud de Confiance 控制台中，前往迁移 > 服务页面。

    前往“迁移服务”

  2. 在注册或迁移开放式湖仓一体下，点击创建迁移。

  3. 在迁移配置下，执行以下操作：

    1. 对于目录类型，请选择外部目录。

    2. 在区域部分中，选择一个区域。所选区域决定了迁移编排和数据传输的运行位置。它还决定了迁移服务在何处使用或创建任何资源，例如网络连接或密钥。

      仅支持区域级 Secret。密钥的区域必须与此字段中的区域一致。

    3. 在迁移显示名称部分，输入此迁移的名称。

  4. 在源系统配置下，执行以下操作：

    1. 在网址部分，输入作为 Apache Iceberg 或 Apache Hive Metastore 入口点的基本端点网址。
    2. 在服务账号部分，从列表中选择一个服务账号。如果未指定，此迁移将使用用户凭据运行。
    3. （可选）在网络连接部分，选择一个网络连接。

  5. 点击继续。

元数据迁移完成后，外部目录中的元数据会存储在您创建 Lakehouse 目录时指定的 Cloud Storage 存储桶中。

价格

将元数据转移到 Lakehouse Iceberg REST 目录表无需付费。转移元数据后，您需要按 Lakehouse 价格付费。