Lakehouse リージョン エンドポイント

このドキュメントでは、Private Service Connect リージョン エンドポイントを使用して Lakehouse ランタイム カタログのリソースにアクセスする方法について説明します。リージョン エンドポイントを使用すると、データ所在地とデータ主権の要件を遵守する方法でワークロードを実行できます。この場合、リクエスト トラフィックはエンドポイントで指定されているリージョンに直接転送されます。

概要

リージョン エンドポイントは、影響を受けるカタログ リソースがエンドポイントで指定されたロケーションに存在する場合にのみ、リクエストの続行を制限します。たとえば、エンドポイント https://biglake.us-central1.rep.googleapis.com を使用してカタログ、Namespace、テーブルにアクセスする場合、カタログが us-central1 にある場合にのみリクエストが処理されます。

リソースが存在する場所とは異なるロケーションを経由してリクエストをルーティングできるグローバル エンドポイントとは異なり、リージョン エンドポイントは、リソースが存在するエンドポイントによって指定されたロケーションにリクエストを制限します。リージョン エンドポイントは、インターネット、Compute Engine 仮想マシンなどの他の Google Cloud リソース、Cloud VPN または Cloud Interconnect を使用するオンプレミス サービス、Virtual Private Cloud（VPC）から受信したリクエストに対して、エンドポイントで指定されたロケーションで Transport Layer Security（TLS）セッションを終端します。

リージョン エンドポイントは、転送中のカタログ リクエストがエンドポイントで指定されたロケーション内に保持されるようにすることで、データ所在地を保証します。サービス メタデータの処理方法について詳しくは、サービスデータに関する注意事項をご覧ください。

Lakehouse ランタイム カタログの次のカタログ エンドポイントは、リージョン エンドポイントで使用できます。

カタログ エンドポイント リージョン エンドポイント URL リファレンス
Apache Iceberg REST カタログ エンドポイント https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog REST
Apache Hive カタログ エンドポイント（プレビュー） https://biglake.LOCATION.rep.googleapis.com/hive/v1 REST

サポートされているロケーション

リージョン エンドポイントは、次のロケーションの Lakehouse ランタイム カタログで使用できます。

  • アジア太平洋

    • デリー asia-south2
    • ムンバイ asia-south1

  • ヨーロッパ

    • ベルギー europe-west1
    • フランクフルト europe-west3
    • ロンドン europe-west2
    • ミラノ europe-west8
    • オランダ europe-west4
    • パリ europe-west9
    • チューリッヒ europe-west6

  • 中東

    • ダンマーム me-central2

  • 南北アメリカ

    • コロンバス（オハイオ州）us-east5
    • ダラス us-south1
    • アイオワ us-central1
    • ラスベガス us-west4
    • ロサンゼルス us-west2
    • モントリオール northamerica-northeast1
    • 北バージニア us-east4
    • オレゴン us-west1
    • ソルトレイクシティ us-west3
    • サウスカロライナ us-east1
    • トロント northamerica-northeast2

サポートされているオペレーションとストレージの場所

リージョン エンドポイントは、エンドポイントで指定されたロケーションに複製されたカタログ リソースにアクセスまたはリソースを変更するオペレーションを実行するためにのみ使用できます。

  • リージョン カタログの分離: https://biglake.LOCATION.rep.googleapis.com を介してカタログを一覧表示すると、LOCATION にあるカタログのみが返されます。LOCATION の外部にあるカタログ、Namespace、テーブルの取得、更新、削除のリクエストは、404 NOT_FOUND エラーを返します。
  • デフォルトのストレージ ロケーション: リージョン エンドポイントを使用してカタログを作成する場合、複数バケット カタログ（CATALOG_TYPE_BIGLAKE）の default_location で指定された Cloud Storage バケット、または単一バケット カタログ（CATALOG_TYPE_GCS_BUCKET）に関連付けられたバケットは LOCATION に存在する必要があります。
  • 複数バケット カタログの制限付きロケーション: 複数バケット カタログの場合、バケットが LOCATION と同じ地理的管轄区域（米国やヨーロッパなど）内にある限り、restricted_locations に追加の Cloud Storage バケットを構成できます。詳細については、マルチバケット カタログをご覧ください。

制限事項

リージョン エンドポイントを使用して次のオペレーションを行うことはできません。

  • エンドポイントで指定されたリージョンの外部にあるカタログ、名前空間、テーブルを読み取るか変更するオペレーション。
  • マルチリージョン エンドポイントのルーティング（US や EU など）。リージョン エンドポイントでは、単一のリージョンを指定する必要があります。

リージョン エンドポイントを使用する場合は、次の制限に注意してください。

ツールとクエリエンジンを構成する

リージョン エンドポイントを使用するように Google Cloud CLI、Apache Spark、Trino、直接 REST API リクエストを構成できます。

gcloud CLI

gcloud biglake コマンドでリージョン エンドポイントを使用するように gcloud CLI を構成するには、api_endpoint_overrides/biglake プロパティを使用するリージョン エンドポイントに設定します。

gcloud config set api_endpoint_overrides/biglake https://biglake.LOCATION.rep.googleapis.com/

または、個々のコマンドに CLOUDSDK_API_ENDPOINT_OVERRIDES_BIGLAKE 環境変数を設定することもできます。

CLOUDSDK_API_ENDPOINT_OVERRIDES_BIGLAKE=https://biglake.LOCATION.rep.googleapis.com/ \
    gcloud biglake iceberg catalogs list --project=PROJECT_ID

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

  • LOCATION: カタログのサポート対象の地域（例: us-central1）。
  • PROJECT_ID: 実際の Google Cloud プロジェクト ID。

Apache Spark

Apache Iceberg REST カタログ エンドポイントに接続するように Spark セッションを構成する場合は、spark.sql.catalog.CATALOG_NAME.uri プロパティをリージョン エンドポイント URL に設定します。

from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
    .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
    .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
    .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
    .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog') \
    .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'bl://projects/PROJECT_ID/catalogs/CATALOG_ID') \
    .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
    .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
    .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
    .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation', 'vended-credentials') \
    .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
    .getOrCreate()

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

  • CATALOG_NAME: ローカル Spark カタログの名前（例: my_catalog）。
  • APP_NAME: Spark セッションの名前。
  • LOCATION: カタログが配置されているサポート対象の地域（例: us-central1）。
  • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
  • CATALOG_ID: 複数バケット カタログの ID。

その他の構成オプションについては、Apache Iceberg REST カタログ エンドポイントを設定するをご覧ください。

Trino

Trino コンポーネントを使用して Managed Service for Apache Spark クラスタを作成する場合は、trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri をリージョン エンドポイント URL に設定します。

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --region=LOCATION \
    --image-version=DATAPROC_VERSION \
    --network=NETWORK_ID \
    --optional-components=TRINO \
    --properties="\
    trino-catalog:CATALOG_NAME.connector.name=iceberg,\
    trino-catalog:CATALOG_NAME.iceberg.catalog.type=rest,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri=https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.warehouse=bl://projects/PROJECT_ID/catalogs/CATALOG_ID,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.biglake.project-id=PROJECT_ID,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager"

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

  • CLUSTER_NAME: クラスタの名前。
  • LOCATION: クラスタとカタログのサポート対象の地域。
  • DATAPROC_VERSION: Managed Service for Apache Spark イメージ バージョン（例: 2.2）。
  • NETWORK_ID: クラスタ ネットワーク ID。
  • CATALOG_NAME: Trino カタログの名前。
  • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
  • CATALOG_ID: 複数バケット カタログの ID。

REST API

REST リクエストをグローバル エンドポイント（https://biglake.googleapis.com）に送信するのではなく、https://biglake.LOCATION.rep.googleapis.com という形式でリクエストをリージョン エンドポイントに送信します。

たとえば、Apache Iceberg REST カタログ エンドポイント拡張機能 API を使用して LOCATION のカタログを一覧表示するには:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    "https://biglake.LOCATION.rep.googleapis.com/iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs"

グローバル API エンドポイントの使用を制限する

リージョン エンドポイントの使用を強制するには、constraints/gcp.restrictEndpointUsage 組織のポリシーの制約を使用して、グローバル API エンドポイント（biglake.googleapis.com）へのリクエストをブロックします。詳細については、エンドポイントの使用を制限するをご覧ください。

次の組織のポリシーの YAML ファイルの例では、グローバル biglake.googleapis.com エンドポイントへのリクエストを拒否し、リージョン エンドポイントへのリクエストを許可しています。

name: projects/PROJECT_ID/policies/gcp.restrictEndpointUsage
spec:
  rules:
  - values:
      deniedValues:
      - under:services/biglake.googleapis.com

次のステップ