外部データ カタログから Apache Iceberg の Lakehouse REST カタログ テーブルにメタデータを移行する

プレビュー

この機能は、サービス固有規約の「一般サービス規約」セクションの「一般提供前のサービス規約」の対象となります。pre-GA の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。 詳細については、リリース ステージの説明をご覧ください。

注: この機能に関するフィードバックやサポートのリクエストについては、[e-mail] までお問い合わせください。

このドキュメントでは、外部データ カタログから Apache Iceberg 用 Lakehouse REST カタログ テーブルにメタデータを移行する方法について説明します。BigQuery Migration Service は、次の外部メタストアからのメタデータの移行をサポートしています。

• Apache Hive メタストア
• Apache Iceberg REST カタログ

制限事項

警告: 移行後に移行元テーブルと移行先テーブルの両方でデータを変更すると、データが失われる可能性があります。

• 外部データ カタログから Apache Iceberg 用 Lakehouse REST カタログ テーブルへのメタデータの移行は、1 回限りの同期です。この機能は継続的または定期的な同期をサポートしていないため、移行後に書き込まれた内容は、再度移行するまで表示されません。
• ネストされた Namespace はサポートされていません。
• Iceberg REST カタログは Parquet データファイルのみをサポートします。
• ボーダーレス レイクハウスは Apache Iceberg V3 テーブルをサポートしていません。
• 外部データ カタログから Apache Iceberg の Lakehouse REST カタログ テーブルへのメタデータの移行では、最大 10,000 個のテーブルの移行のみがサポートされます。ワークロードで 10,000 個を超えるテーブルを処理する必要がある場合は、ワークロードを複数の移行に分割することをおすすめします。
• 外部データ カタログから Apache Iceberg 用 Lakehouse REST カタログ テーブルへのメタデータの移行では、組織のポリシーを使用してドメイン制限付き共有を適用することはできません。

始める前に

外部データカタログからメタデータを移行する前に、次のセクションの手順を行う必要があります。

API を有効にする

BigLake、BigQuery Data Transfer、BigQuery Migration、Secret Manager、Storage Transfer の各 API がまだ有効になっていない場合は、有効にします。

API を有効にするために必要なロール

API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を通じてこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を通じてこの権限を取得できます。ロールを付与する方法を確認する。

API を有効にする

Data Transfer API を有効にすると、サービス エージェントが作成されます。

権限を構成する

1. 転送を作成するユーザーまたはサービス アカウントには、BigQuery 管理者ロール（roles/bigquery.admin）が付与されている必要があります。サービス アカウントを使用する場合、そのアカウントは転送の作成にのみ使用されます。

2. Data Transfer API を有効にすると、サービス エージェント（P4SA）が作成されます。

   Hive Metastore 転送を実行するために必要な権限がサービス エージェントに付与されるように、プロジェクトに対する次の IAM ロールをサービス エージェントに付与するよう管理者に依頼してください。

   重要: これらのロールは、ユーザー アカウントではなくサービス エージェントに付与する必要があります。正しいプリンシパルにロールを付与しないと、権限エラーが発生する可能性があります。
   • Storage Transfer 管理者 （roles/storagetransfer.admin）
   • Service Usage コンシューマー （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:[e-mail] --role
   roles/iam.serviceAccountTokenCreator

4. Storage Transfer Service サービス エージェント（[e-mail]）に、プロジェクト内の次のロールを付与します。

   • roles/storage.admin
   • オンプレミス/HDFS から移行する場合は、roles/storagetransfer.serviceAgent ロールも付与する必要があります。

   より詳細な権限を構成することもできます。詳細については、次のガイドをご覧ください。

   • HDFS 権限
   • Amazon S3 と Microsoft Azure の権限

必要なユーザーロールと権限

サービス エージェントに Apache Iceberg 移行用の Lakehouse REST カタログ テーブルの作成、変更、実行に必要な権限が付与されるようにするには、ユーザーのサービス エージェントに次の IAM ロールを付与するよう管理者に依頼してください。

重要: これらのロールは、ユーザー アカウントではなくサービス エージェントに付与する必要があります。正しいプリンシパルにロールを付与しないと、権限エラーが発生する可能性があります。

• サービス アカウント ユーザー（roles/iam.serviceAccountUser）
• 移行管理編集者 （roles/bigquerymigration.migrationEditor）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

管理者は、カスタムロールや他の事前定義ロールを使用して、サービス エージェントに必要な権限を付与することもできます。

サービス アカウントに必要なロールと権限

Apache Iceberg の移行用に顧客が提供したサービス アカウントに Lakehouse REST カタログ テーブルの作成、変更、実行に必要な権限があることを確認するには、顧客が提供したサービス アカウントに次の IAM ロールを付与するよう管理者に依頼してください。

重要: これらのロールは、ユーザー アカウントではなく、お客様が提供するサービス アカウントに付与する必要があります。正しいプリンシパルにロールを付与しないと、権限エラーが発生する可能性があります。

• ネットワーク アタッチメントへのアクセス: サービス アカウントに対する Compute ネットワーク管理者 （roles/compute.networkAdmin）
• BigQuery Data Transfer Service へのアクセス: サービス アカウントに対する BigQuery 管理者 （roles/bigquery.admin）
• Lakehouse リソースへのアクセス: サービス アカウントに対する BigLake 編集者 （roles/biglake.editor）
• シークレットへのアクセス: お客様が提供したシークレットに対する Secret Manager のシークレット アクセサー （roles/secretmanager.secretAccessor）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

管理者は、カスタムロールや他の事前定義ロールを使用して、顧客が提供したサービス アカウントに必要な権限を付与することもできます。

また、BigQuery Migration Service のサービス ID を作成し、roles/iam.serviceAccountTokenCreator ロールを付与する必要があります。

サービス ID を作成するには、次のコマンドを実行します。

gcloud beta services identity create --service=bigquerymigration.googleapis.com --project=PROJECT_ID

サービス エージェントにロールを付与するには、次のコマンドを実行します。

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT --member serviceAccount:[e-mail] --role roles/iam.serviceAccountTokenCreator --project PROJECT_ID

次のように置き換えます。

• SERVICE_ACCOUNT: 顧客が提供したサービス アカウントの ID
• PROJECT_ID: プロジェクト ID
• PROJECT_NUMBER: プロジェクト番号

シークレットを構成する

Apache Iceberg REST カタログに移行する場合は、移行を承認するためのシークレットを作成する必要があります。シークレットは次の形式でフォーマットする必要があります。

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

次のように置き換えます。

• CLIENT_ID: OAuth 2.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. Google Cloud コンソールで、[移行] > [サービス] ページに移動します。

   移行サービスに移動する

2. [オープン レイクハウスの登録または移行] で、[移行を作成] をクリックします。

3. [移行構成] で、次の操作を行います。

   1. カタログタイプで、外部カタログを選択します。

   2. [リージョン] でリージョンを選択します。選択したリージョンによって、移行オーケストレーションとデータ転送が実行される場所が決まります。また、移行サービスがネットワーク アタッチメントやシークレットなどのリソースを使用または作成する場所も決定します。

      リージョン シークレットのみがサポートされています。シークレットのリージョンは、このフィールドのリージョンと一致する必要があります。

   3. [移行の表示名] に、この移行の名前を入力します。

4. [ソースシステムの構成] で、次の操作を行います。

   1. [URL] に、Apache Iceberg または Apache Hive metastore のエントリ ポイントとして機能するベース エンドポイント URL を入力します。
   2. [サービス アカウント] で、リストからサービス アカウントを選択します。指定しない場合、この移行はユーザー認証情報を使用して実行されます。
   3. （省略可）[ネットワーク アタッチメント] で、ネットワーク アタッチメントを選択します。

5. [続行] をクリックします。

メタデータの移行が完了すると、外部カタログのメタデータは、Lakehouse カタログの作成時に指定した Cloud Storage バケットに保存されます。

料金

メタデータを Lakehouse Iceberg REST カタログ テーブルに転送する費用は発生しません。メタデータが転送されると、Lakehouse の料金が適用されます。