將中繼資料從外部 Data Catalog 遷移至 Lakehouse REST 目錄資料表 (適用於 Apache Iceberg)

本文說明如何將中繼資料從外部 Data Catalog，遷移至 Lakehouse REST catalog tables for Apache Iceberg。BigQuery 遷移服務支援從下列外部 metastore 遷移中繼資料：

• Apache Hive metastore
• Apache Iceberg REST 目錄

限制

• 從外部 Data Catalog 遷移至 Apache Iceberg 的 Lakehouse REST 目錄資料表，屬於一次性同步作業。這項功能不支援持續或定期同步處理，因此在遷移後寫入的任何資料，都必須再次遷移才會顯示。
• 不支援巢狀命名空間。
• Iceberg REST 目錄僅支援 Parquet 資料檔案。
• Borderless Lakehouse 不支援 Apache Iceberg V3 資料表。
• 從外部 Data Catalog 遷移中繼資料至 Apache Iceberg 的 Lakehouse REST 目錄資料表時，最多只能遷移 10,000 個資料表。如果工作負載需要處理超過 10,000 個資料表，建議您將工作負載拆分為多項遷移作業。
• 將中繼資料從外部 Data Catalog 遷移至 Apache Iceberg 的 Lakehouse REST 目錄資料表時，不支援使用組織政策強制執行網域限制共用。

事前準備

您必須先完成下列各節中的步驟，才能從外部資料目錄遷移中繼資料。

啟用 API

啟用 BigLake、BigQuery Data Transfer、BigQuery Migration、Secret Manager、Storage Transfer API (如有尚未啟用的 API)。

啟用 API

啟用 Data Transfer API 時，系統會建立服務代理。

設定權限

1. 建立移轉作業的使用者或服務帳戶應具備 BigQuery 管理員角色 (roles/bigquery.admin)。如果使用服務帳戶，該帳戶僅用於建立移轉作業。

2. 啟用 Data Transfer API 後，系統會建立服務代理 (P4SA)。

   為確保服務代理具備執行 Hive Metastore 移轉作業所需的權限，請要求管理員在專案中，為服務代理授予下列 IAM 角色：

   • Storage 移轉作業管理員 (roles/storagetransfer.admin)
   • 服務使用情形消費者 (roles/serviceusage.serviceUsageConsumer)
   • 儲存空間管理員 (roles/storage.admin)
   • 如要將中繼資料遷移至 Lakehouse 執行階段目錄 (Iceberg REST 目錄或 Hive 目錄)：BigLake 管理員 (roles/biglake.admin)

   如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

   管理員或許也能透過自訂角色或其他預先定義的角色，將必要權限授予服務代理。

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 移轉服務代理 (project-PROJECT_NUMBER@storage-transfer-service.s3ns-system.iam.gserviceaccount.com)：

   • roles/storage.admin
   • 如果您是從地端部署或 HDFS 遷移，也必須授予 roles/storagetransfer.serviceAgent 角色。

   您也可以設定更精細的權限。詳情請參閱下列指南：

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

必要的使用者角色和權限

為確保服務代理具備必要權限，可建立、修改及執行 Lakehouse REST 目錄資料表，以便遷移 Apache Iceberg，請要求管理員為使用者授予服務代理下列 IAM 角色：

• 服務帳戶使用者 (roles/iam.serviceAccountUser)
• 遷移作業管理編輯者 (roles/bigquerymigration.migrationEditor)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

管理員或許也能透過自訂角色或其他預先定義的角色，將必要權限授予服務代理。

必要的服務帳戶角色和權限

為確保客戶提供的服務帳戶具備必要權限，可建立、修改及執行 Lakehouse REST 目錄資料表，以便遷移 Apache Iceberg，請要求管理員將下列 IAM 角色授予客戶提供的服務帳戶：

• 網路連結的存取權：服務帳戶的 Compute 網路管理員 (roles/compute.networkAdmin)
• BigQuery 資料移轉服務的存取權：服務帳戶的 BigQuery 管理員 (roles/bigquery.admin)
• 存取湖倉資源：服務帳戶的 BigLake 編輯者 (roles/biglake.editor)
• 密鑰存取權：客戶提供的密鑰具備 Secret Manager 密鑰存取者 (roles/secretmanager.secretAccessor) 角色

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

管理員或許也能透過自訂角色或其他預先定義的角色，將必要權限授予客戶提供的服務帳戶。

您也必須為 BigQuery 遷移服務建立服務身分，並授予 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：專案編號

設定密鑰

如要遷移至 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 bucket。

遷移中繼資料

如要開始將中繼資料遷移至 Lakehouse Iceberg REST 目錄資料表，請按照下列步驟操作：

1. 在 Cloud de Confiance 控制台，依序前往「Migration」(遷移) >「Services」(服務) 頁面。

   前往「遷移服務」

2. 在「註冊或遷移開放式湖倉」下方，點選「建立遷移作業」。

3. 在「Migration configuration」(遷移設定) 下方，執行下列操作：

   1. 在「目錄類型」部分，選取外部目錄。

   2. 在「Region」(區域) 選取區域。所選區域會決定遷移自動化調度管理和資料移轉的執行位置。此外，這項設定也會決定遷移服務使用或建立資源的位置，例如網路連結或 Secret。

      僅支援區域密鑰。密鑰的區域必須與這個欄位中的區域相符。

   3. 在「遷移作業顯示名稱」部分，輸入這項遷移作業的名稱。

4. 在「Source system configuration」(來源系統設定) 下方，執行下列操作：

   1. 在「URL」(網址) 部分，輸入做為 Apache Iceberg 或 Apache Hive metastore 進入點的基本端點網址。
   2. 在「服務帳戶」部分，從清單中選取服務帳戶。如未指定，這項遷移作業會使用使用者憑證執行。
   3. (選用) 在「Network attachment」(網路連結) 部分，選取網路連結。

5. 按一下「繼續」。

中繼資料遷移完成後，外部目錄的中繼資料會儲存在您建立 Lakehouse 目錄時指定的 Cloud Storage bucket。

定價

將中繼資料移轉至 Lakehouse Iceberg REST 目錄資料表，不需支付任何費用。中繼資料轉移後，即適用 Lakehouse 定價。