HDFS データレイクからテーブルを移行する

このドキュメントでは、Apache Hadoop Distributed File System（HDFS）データレイク テーブルを Trusted Cloudに移行する方法について説明します。

BigQuery Data Transfer Service の HDFS データレイク移行コネクタを使用すると、オンプレミス環境とクラウド環境の両方で、さまざまな Hadoop ディストリビューションから Hive テーブルと Iceberg テーブルを Trusted Cloudに移行できます。

HDFS データレイク コネクタを使用すると、Cloud Storage をファイルの基盤となるストレージとして使用しながら、HDFS データレイク テーブルを Dataproc Metastore と BigLake Metastore の両方に登録できます。

次の図は、Hadoop クラスタからのテーブル移行プロセスの概要を示しています。

Hive データレイクから BigQuery へのテーブル移行の概要。

制限事項

HDFS データレイクの転送には、次の制限事項があります。

  • Iceberg テーブルを移行するには、オープンソース エンジン（Spark や Flink など）の書き込みアクセスを許可し、BigQuery の読み取りアクセスを許可するために、BigLake Metastore にテーブルを登録する必要があります。
  • Hive テーブルを移行するには、テーブルを Dataproc Metastore に登録して、オープンソース エンジンの書き込みアクセスを許可し、BigQuery の読み取りアクセスを許可する必要があります。
  • HDFS データレイク テーブルを BigQuery に移行するには、bq コマンドライン ツールを使用する必要があります。

始める前に

HDFS データレイク転送のスケジュールを設定する前に、次の操作を行う必要があります。

移行するファイル用の Cloud Storage バケットを作成する

移行するデータレイク ファイルの移行先となる Cloud Storage バケットを作成します。このドキュメントでは、このバケットを 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 バケット（このドキュメントでは DUMPER_BUCKET と呼びます）に生成します。

変換構成 YAML ファイル

接尾辞 .config.yaml を含む名前の変換構成 YAML（例: translation.config.yaml）を作成し、hive-dumper-output.zip を格納しているバケットにアップロードします。次の例のように、HDFS パスを Cloud Storage のマネージド フォルダにマッピングするように変換構成 YAML を構成します。

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

MIGRATION_BUCKET は、ファイルの移行先となる Cloud Storage バケットの名前に置き換えます。

location_expression フィールドは、Common Expression Language（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: テーブル マッピング YAML ファイルを格納する Cloud Storage バケットのベース URI。たとえば、gs://output_bucket/tables/ です。
  • DUMPER_BUCKET: hive-dumper-output.zip と構成 YAML ファイルを格納している Cloud Storage バケットのベース URI。
  • TOKEN: OAuth トークン。これは、コマンドラインでコマンド gcloud auth print-access-token を使用して生成できます。
  • PROJECT_ID: 変換を処理するプロジェクト。
  • LOCATION: ジョブが処理されるロケーション。たとえば、eu や us です。

Translation Service 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 フォルダに保存されている複数のマッピング ファイル（テーブルごとに 1 つ）で構成される場合があります。

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.objectViewer ではなく roles/storage.objectAdmin ロールと roles/bigquery.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

Storage Transfer エージェントを構成する

HDFS データレイクの転送に必要な Storage Transfer エージェントを設定するには、次の操作を行います。

  1. Hadoop クラスタで Storage Transfer エージェントを実行するように権限を構成します。
  2. オンプレミス エージェント マシンに Docker をインストールします。
  3. Trusted Cloud by S3NS プロジェクトに Storage Transfer Service エージェント プールを作成します。
  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 の URL を指定します。

メタデータを BigLake Metastore に転送する場合、転送構成で destination_dataproc_metastore フィールドを指定する必要はありません。システムは、生成された YAML マッピング ファイル内の targetName フィールドから、移行先の BigQuery データセットを自動的に判断します。targetName フィールドは、2 つの部分からなる識別子の形式で指定します（例: 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 時間以上にする必要があります。

1 回限りの転送の場合は、転送構成に end_time フラグを追加して、転送を 1 回だけ実行できます。

HDFS データレイク転送をモニタリングする

HDFS データレイク転送のスケジュールを設定したら、bq コマンドライン ツールのコマンドを使用して転送ジョブをモニタリングできます。転送ジョブのモニタリングについては、転送を表示するをご覧ください。

テーブルの移行ステータスをトラッキングする

dwh-dts-status ツールを実行して、転送構成または特定のデータベース内のすべての転送済みテーブルのステータスをモニタリングすることもできます。dwh-dts-status ツールを使用して、プロジェクト内のすべての転送構成を一覧表示することもできます。

始める前に

dwh-dts-status ツールを使用するには、まず次の操作を行います。

  1. dwh-migration-tools GitHub リポジトリから dwh-migration-tool パッケージをダウンロードして、dwh-dts-status ツールを入手します。

  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 のいずれかの値になります。