從 HDFS 資料湖遷移資料表

本文說明如何將 Apache Hadoop 分散式檔案系統 (HDFS) 資料湖資料表遷移至 Trusted Cloud。

您可以使用 BigQuery 資料移轉服務中的 HDFS 資料湖遷移連接器，將 Hive 和 Iceberg 資料表從各種 Hadoop 發行版本 (包括內部部署和雲端環境) 遷移至 Trusted Cloud。

透過 HDFS 資料湖連接器，您可以使用 Cloud Storage 做為檔案的基礎儲存空間，同時向 Dataproc Metastore 和 BigLake Metastore 註冊 HDFS 資料湖表格。

下圖概略說明從 Hadoop 叢集遷移資料表的程序。

從 Hive 資料湖遷移資料表至 BigQuery 的總覽。

限制

HDFS 資料湖移轉作業有下列限制：

  • 如要遷移 Iceberg 資料表，您必須向 BigLake Metastore 註冊資料表，允許開放原始碼引擎 (例如 Spark 或 Flink) 寫入資料，並允許 BigQuery 讀取資料。
  • 如要遷移 Hive 資料表，您必須向 Dataproc Metastore 註冊資料表，才能允許開放原始碼引擎寫入資料，並允許 BigQuery 讀取資料。
  • 您必須使用 bq 指令列工具，將 HDFS 資料湖資料表遷移至 BigQuery。

事前準備

排定 HDFS 資料湖移轉作業前，請務必完成下列事項：

建立 Cloud Storage bucket，存放遷移的檔案

建立 Cloud Storage bucket，做為遷移資料湖泊檔案的目的地。本文將這個值區稱為 MIGRATION_BUCKET。

必要檔案

如要排定 HDFS 資料湖泊轉移作業，您必須先在 Cloud Storage 值區中備妥下列遷移檔案：

  • 解壓縮的中繼資料檔案 (hive-dumper-output.zip)
  • 轉譯設定 YAML 檔案 (*.config.yaml)
  • 對應 YAML 檔案的表格

下列各節將說明如何建立這些檔案。

hive-dumper-output.zip

執行 dwh-migration-dumper 工具，擷取 Apache Hive 的中繼資料。這項工具會產生名為 hive-dumper-output.zip 的檔案，並儲存至 Cloud Storage bucket (本文稱為 DUMPER_BUCKET)。

轉譯設定 YAML 檔案

建立轉譯設定 YAML，名稱包含 .config.yaml 後置字串 (例如 translation.config.yaml)，然後上傳至包含 hive-dumper-output.zip 的相同值區。設定轉換設定 YAML，將 HDFS 路徑對應至 Cloud Storage 受管理資料夾，類似下列範例：

type: object_rewriter
relation:
- match:
    relationRegex: ".*"
  external:
    location_expression: "'gs://MIGRATION_BUCKET/' + table.schema + '/' + table.name"

將 MIGRATION_BUCKET 替換為要存放遷移檔案的 Cloud Storage bucket 名稱。

location_expression 欄位是一般運算語言 (CEL) 運算式。

如要進一步瞭解這個設定 YAML，請參閱建立設定 YAML 檔案的指南。

產生資料表對應 YAML 檔案

如要產生資料表對應 YAML 檔案，請執行下列指令：

  curl -d '{
    "tasks": {
        "string": {
          "type": "HiveQL2BigQuery_Translation",
          "translation_details": {
              "target_base_uri": "TRANSLATION_OUTPUT_BUCKET",
              "source_target_mapping": {
                "source_spec": {
                    "base_uri": "DUMPER_BUCKET"
                }
              },
              "target_types": ["metadata"]
          }
        }
    }
    }' \
    -H "Content-Type:application/json" \
    -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows

更改下列內容：

  • TRANSLATION_OUTPUT_BUCKET：Cloud Storage 儲存空間的基礎 URI，用於存放表格對應 YAML 檔案。例如：gs://output_bucket/tables/。
  • DUMPER_BUCKET：Cloud Storage 值區的基本 URI，其中包含 hive-dumper-output.zip 和設定 YAML 檔案。
  • TOKEN：OAuth 權杖。您可以在指令列中透過 gcloud auth print-access-token 指令產生這項檔案。
  • PROJECT_ID：用於處理翻譯的專案。
  • LOCATION：處理作業的位置。例如 eu 或 us。

執行時，翻譯服務 API 會傳回 WORKFLOW_ID，並啟動非同步背景工作。您可以使用下列指令監控這項工作的狀態：

  curl \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer TOKEN" -X GET https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

完成後，系統會建立資料表對應 YAML 檔案。 您的表格對應 YAML 檔案可能包含多個對應檔案 (每個表格各有一個)，並儲存在 Cloud Storage 資料夾中。

啟用 API

在Trusted Cloud 專案中啟用下列 API：

  • Data Transfer API
  • Storage Transfer API

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

設定權限

  1. 建立服務帳戶，並授予 BigQuery 管理員角色 (roles/bigquery.admin)。這個服務帳戶用於建立移轉設定。
  2. 啟用 Data Transfer API 時，系統會建立服務代理人 (P4SA)。授予下列角色：
    • roles/metastore.metadataOwner
    • roles/storagetransfer.admin
    • roles/serviceusage.serviceUsageConsumer
    • roles/storage.objectViewer
      • 如果您要遷移 BigLake Iceberg 資料表的中繼資料，請授予 roles/storage.objectAdmin 和 roles/bigquery.admin 角色，而非 roles/storage.objectViewer。

  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

設定 Storage Transfer Agent

如要設定 HDFS 資料湖移轉所需的儲存空間移轉代理程式，請按照下列步驟操作：

  1. 設定權限，在 Hadoop 叢集上執行 Storage 移轉代理程式。
  2. 在內部部署代理程式機器上安裝 Docker。
  3. 在 Trusted Cloud by S3NS 專案中建立 Storage 移轉服務代理程式集區。
  4. 在您的地端部署代理程式電腦上安裝代理程式。

排定 HDFS 資料湖移轉作業

如要排定 HDFS 資料湖移轉作業，請輸入 bq mk 指令並加上移轉建立作業旗標 --transfer_config：

  bq mk --transfer_config
  --data_source=hadoop
  --display_name='TRANSFER_NAME'
  --service_account_name='SERVICE_ACCOUNT'
  --project_id='PROJECT_ID'
  --location='REGION'
  --params='{"table_name_patterns":"LIST_OF_TABLES",
    "agent_pool_name":"AGENT_POOL_NAME",
    "destination_dataproc_metastore":"DATAPROC_METASTORE",
    "translation_output_gcs_path":"gs://TRANSLATION_OUTPUT_BUCKET/metadata/config/default_database/",
    "table_metadata_path":"gs://DUMPER_BUCKET/hive-dumper-output.zip"}'

更改下列內容：

  • TRANSFER_NAME：移轉設定的顯示名稱。移轉作業名稱可以是任意值，日後需要修改移轉作業時，能夠據此識別即可。
  • SERVICE_ACCOUNT：用於驗證轉移作業的服務帳戶名稱。服務帳戶應由用於建立轉移作業的 project_id 擁有，且應具備所有必要權限。
  • PROJECT_ID：您的 Trusted Cloud by S3NS 專案 ID。如未提供 --project_id 指定特定專案，系統會使用預設專案。
  • REGION：這項移轉設定的位置。
  • LIST_OF_TABLES：要轉移的實體清單。使用階層式命名規格 - database.table。這個欄位支援 RE2 規則運算式，可指定資料表。例如：
    • db1..*：指定資料庫中的所有資料表
    • db1.table1;db2.table2：資料表清單
  • AGENT_POOL_NAME：用於建立代理程式的代理程式集區名稱。
  • DATAPROC_METASTORE：受管理 OSS 目的地的目的地 Dataproc Metastore。如要改用 BigLake Metastore，可以從這項移轉設定中省略這個欄位。如要進一步瞭解如何使用 BigLake Metastore 遷移中繼資料，請參閱中繼資料遷移。

執行這項指令，建立移轉設定並開始移轉 HDFS 資料湖。根據預設，系統每隔 24 小時就會執行移轉作業，但您可以使用移轉排程選項進行設定。

轉移完成後，Hadoop 叢集中的資料表就會遷移至 MIGRATION_BUCKET。

資料擷取選項

以下各節提供更多資訊，說明如何設定 HDFS 資料湖移轉作業。

中繼資料遷移

中繼資料可以遷移至 Dataproc Metastore 或 BigLake Metastore，而基礎資料則儲存在 Cloud Storage 中。

如要將中繼資料轉移至 Dataproc Metastore，請在 destination_dataproc_metastore 欄位中指定 Metastore 的網址。

如要將中繼資料移轉至 BigLake 中繼資料存放區，您不需要在移轉設定中指定 destination_dataproc_metastore 欄位。系統會從產生的 YAML 對應檔案中，targetName 欄位自動判斷目的地 BigQuery 資料集。 targetName 欄位的格式為兩部分 ID，例如 bigquery_dataset_name.bigquery_table_name。根據預設，命名方式會與來源系統一致。請務必確認來源結構定義名稱的 BigQuery 資料集存在，否則請先建立該資料集，再執行移轉作業。

如要使用其他 BigQuery 資料集，您必須在 DUMPER_BUCKET 中提供額外的設定 YAML 檔案 (後方加上 config.yaml)，其中包含物件重寫規則集，然後產生轉譯對應。以下範例是規則集，可將名為 my_hive_db 的來源資料庫對應至名為 my_bq_dataset 的 BigQuery 資料集：

relation:
  - match:
      schema: my_hive_db
    outputName:
      database: null
      schema: my_bq_dataset

schema 參數必須對應至 BigQuery 資料集名稱，而 relation 參數則必須對應至資料表名稱。詳情請參閱「輸出名稱對應」。

database 參數也必須設為 null。

增量轉移

如果移轉設定採用週期性時間表，後續每次移轉作業都會更新 Trusted Cloud by S3NS 資料表，反映來源資料表的最新變更。舉例來說，所有插入、刪除或更新作業 (含結構定義變更) 都會反映在 Trusted Cloud by S3NS 中，每次轉移都會更新。

轉移排程選項

根據預設，系統會排定每 24 小時執行一次移轉作業。如要設定移轉作業的執行頻率，請在移轉設定中加入 --schedule 標記，並使用schedule 語法指定移轉時間表。HDFS 資料湖轉移作業的執行間隔至少須為 24 小時。

如要進行一次性移轉，您可以在移轉設定中加入 end_time 旗標，只執行一次移轉。

監控 HDFS 資料湖移轉作業

排定 HDFS 資料湖移轉作業後，您可以使用 bq 指令列工具指令監控移轉工作。如要瞭解如何監控轉移作業，請參閱「查看轉移作業」。

追蹤表格遷移狀態

您也可以執行 dwh-dts-status 工具，監控轉移設定或特定資料庫中所有轉移資料表的狀態。您也可以使用 dwh-dts-status 工具列出專案中的所有移轉設定。

事前準備

使用 dwh-dts-status 工具前，請先完成下列步驟：

  1. 如要取得 dwh-dts-status 工具，請從 dwh-migration-tools GitHub 存放區下載 dwh-migration-tool 封裝。

  2. 使用下列指令驗證帳戶： Trusted Cloud by S3NS 

    gcloud auth application-default login

    詳情請參閱「應用程式預設憑證的運作方式」。

  3. 確認使用者具備 bigquery.admin 和 logging.viewer 角色。如要進一步瞭解 IAM 角色，請參閱存取權控管參考資料。

列出專案中的所有移轉設定

如要列出專案中的所有移轉設定，請使用下列指令：

  ./dwh-dts-status --list-transfer-configs --project-id=[PROJECT_ID] --location=[LOCATION]

更改下列內容：

  • PROJECT_ID：執行轉移作業的 Trusted Cloud by S3NS 專案 ID。
  • LOCATION：建立轉移設定的位置。

這個指令會輸出表格，其中列出移轉設定名稱和 ID。

查看設定中所有表格的狀態

如要查看轉移設定中所有資料表的狀態，請使用下列指令：

  ./dwh-dts-status --list-status-for-config --project-id=[PROJECT_ID] --config-id=[CONFIG_ID] --location=[LOCATION]

更改下列內容：

  • PROJECT_ID：執行轉移作業的 Trusted Cloud by S3NS 專案 ID。
  • LOCATION：建立轉移設定的位置。
  • CONFIG_ID：指定轉移設定的 ID。

這項指令會輸出表格，列出指定移轉設定中的資料表及其移轉狀態。轉移狀態可以是下列其中一個值：PENDING、RUNNING、SUCCEEDED、FAILED、CANCELLED。

查看資料庫中所有資料表的狀態

如要查看從特定資料庫轉移的所有資料表狀態，請使用下列指令：

  ./dwh-dts-status --list-status-for-database --project-id=[PROJECT_ID] --database=[DATABASE]

更改下列內容：

  • PROJECT_ID：執行轉移作業的 Trusted Cloud by S3NS 專案 ID。
  • DATABASE：指定資料庫的名稱。

這項指令會輸出表格，列出指定資料庫中的資料表及其移轉狀態。轉移狀態可以是下列其中一個值：PENDING、RUNNING、SUCCEEDED、FAILED、CANCELLED。