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

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

• Apache Hive Metastore
• Apache Iceberg REST Catalog

限制

• 从外部数据目录到 Lakehouse REST 目录表的元数据迁移（针对 Apache Iceberg）是一次性同步。此功能不支持持续或定期同步，因此在迁移后进行的任何写入操作在您再次迁移之前都不可见。
• 不支持嵌套命名空间。
• Iceberg REST 目录仅支持 Parquet 数据文件。
• 湖仓一体不支持 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

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

配置权限

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

2. 启用 Data Transfer API 后，系统会创建一个服务代理 (P4SA)。

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

   • Storage Transfer Admin (roles/storagetransfer.admin)
   • Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
   • Storage Admin (roles/storage.admin)
   • 如需将元数据迁移到 Lakehouse 运行时目录（Iceberg REST 目录或 Hive 目录），您需要拥有 BigLake Admin (roles/biglake.admin) 角色
   • 如需将元数据迁移到 Dataproc Metastore，您需要具备以下角色： Dataproc Metastore Data Owner (roles/metastore.metadataOwner)

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

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

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

   gcloud iam service-accounts add-iam-policy-binding
   SERVICE_ACCOUNT --member
   serviceAccount:service-PROJECT_NUMBER@gcp-sa-bigquerydatatransfer. --role
   roles/iam.serviceAccountTokenCreator

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

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

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

   • HDFS 权限
   • Amazon S3 和 Microsoft Azure 权限

所需的用户角色和权限

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

• Service Account User (roles/iam.serviceAccountUser)
• Migration Management Editor (roles/bigquerymigration.migrationEditor)

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

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

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

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

• 对网络连接的访问权限：服务账号的 Compute Network Admin (roles/compute.networkAdmin)
• 对 BigQuery Data Transfer Service 的访问权限：服务账号的 BigQuery Admin (roles/bigquery.admin)
• 对 Lakehouse 资源的访问权限： 服务账号的 BigLake Editor (roles/biglake.editor)
• 对密钥的访问权限： 客户提供的密钥的 Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)

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

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

您还必须为 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. --role roles/iam.serviceAccountTokenCreator --project PROJECT_ID

替换以下内容：

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

配置 Secret

如果您要迁移到 Apache Iceberg REST Catalog，则必须创建 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 目录的 realm。此字段仅适用于 Apache Polaris，是必填字段。例如 FINANCE。
• SCOPE：（可选）OAuth2.0 范围。默认值为 PRINCIPAL_ROLE:ALL。

创建 Lakehouse 目录

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

迁移元数据

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

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

   前往“迁移服务”

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

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

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

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

      仅支持区域级密钥。密钥的区域必须与此字段中的区域相匹配。

   3. 在迁移显示名称字段中，输入相应迁移的名称。

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

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

5. 点击继续。

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

价格

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