将元数据从外部数据目录迁移到 Lakehouse REST 目录表（适用于 Apache Iceberg）

本文档介绍了如何将元数据从外部数据目录迁移到 Lakehouse REST 目录表（适用于 Apache Iceberg）。BigQuery Migration Service 支持从以下外部元数据存储区迁移元数据：

  • Apache Hive Metastore
  • Apache Iceberg REST 目录

限制

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

准备工作

如需从外部数据目录迁移元数据，您必须完成以下部分中的步骤。

启用 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. 启用 Data Transfer 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 以授权迁移。Secret 必须采用以下格式：

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

替换以下内容：

  • CLIENT_ID：OAuth2.0 客户端 ID
  • CLIENT_SECRET：OAuth2.0 客户端密钥
  • POLARIS_REALM：Polaris 目录的领域。此字段仅适用于 Apache Polaris。例如，FINANCE。
  • SCOPE：（可选）OAuth2.0 范围。默认值为 PRINCIPAL_ROLE:ALL。

创建 Lakehouse 目录

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

迁移元数据

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

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

    前往迁移服务

  2. 在注册或迁移开放式 Lakehouse 下，点击创建迁移。

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

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

    2. 对于区域，选择一个区域。所选区域决定了迁移编排和数据转移的运行位置。它还决定了迁移服务使用或创建任何资源（例如网络连接或 Secret）的位置。

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

    3. 对于迁移显示名称，输入此迁移的名称。

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

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

  5. 点击继续 。

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

价格

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