カタログを作成

カタログ エンドポイント（Apache Iceberg REST カタログ エンドポイントや Apache Hive カタログ エンドポイントなど）を作成すると、Lakehouse ランタイム カタログ内に管理エンドポイントが確立されます。

このエンドポイントは基盤となる Cloud Storage バケットを指し、クエリエンジンとオープンソース ワークロードがテーブルを直接操作できるメタデータ レイヤを提供します。

Lakehouse for Apache Iceberg のカタログ エンドポイントを作成するときに、ストレージ アクセス委任のエンドユーザー認証情報または認証情報ベンディング モードを選択できます。

始める前に

  1. Lakehouse ランタイム カタログについてを読んで、Lakehouse ランタイム カタログの仕組みとサービスの制限事項を確認します。
    2. Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、 アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

    In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

    Verify that billing is enabled for your Google Cloud project.

    Enable the BigLake API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

    Verify that billing is enabled for your Google Cloud project.

    Enable the BigLake API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

必要なロール

カタログの作成とテーブルの登録に必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

  • カタログを作成する:
  • テーブルを登録する: プロジェクトに対する BigLake 管理者 （roles/biglake.admin）。マルチバケット カタログにテーブルを登録するには、BigLake 管理者ロールに含まれている特定のテーブル登録権限（biglake.tables.register）が必要です。
  • 認証情報ベンディング モードで自動プロビジョニングされたカタログ サービス アカウントを使用する: ターゲット Cloud Storage バケットに対する Storage オブジェクト ユーザー （roles/storage.objectUser）。カタログを作成したら、ストレージ バケットに対する Storage オブジェクト ユーザーロール（roles/storage.objectUser）を自動プロビジョニングされたサービス アカウントに明示的に付与します。

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

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

カタログを作成

カタログを作成します。

コンソール

マルチバケット（bl://）カタログを作成する（推奨）

単一バケット（gs://）カタログを作成する

  1. Google Cloud コンソールで、[Lakehouse] ページを開きます。

    [Lakehouse] に移動

  2. カタログを作成を選択します。[カタログの作成] ページが開きます。

  3. カタログの構成を選択します。

    • Apache Iceberg REST カタログを作成するには、[Iceberg REST カタログ] を選択します。

  4. カタログを構成します。

    • [Iceberg REST catalog] を選択した場合は、カタログ タイプに [Cloud Storage バケット] を選択し、カタログで使用する Cloud Storage バケットを選択します。
    • [Hive catalog] を選択した場合は、一意のカタログ名を入力し、関連する Cloud Storage パスを選択します。

  5. [認証方法] で、[エンドユーザー認証情報] または [認証情報ベンディング モード] を選択します。

    [認証情報ベンディング モード] を選択した場合、自動プロビジョニングされた Lakehouse ランタイム カタログ サービス アカウントには、関連付けられているすべての Cloud Storage バケットに対する明示的な Storage オブジェクト ユーザー ロール（roles/storage.objectUser）が必要です。デフォルトでは、アクセス権はまったくありません。このロールがないと、ベンダー認証情報にはストレージ書き込みを実行するのに十分なスコープがありません。

  6. [作成] を選択します。

    カタログが作成され、[カタログの詳細] ページが開きます。

  7. [認証方法] で、[バケット権限を設定] を選択します。

  8. ダイアログで [確認] を選択します。

    これにより、カタログのサービス アカウントに関連付けられているすべてのストレージ バケットに Storage オブジェクト ユーザーロール（roles/storage.objectUser）があることが確認されます。gcloud または Terraform を使用してカタログを作成する場合は、このロールを手動で付与する必要があります。

gcloud

マルチバケット（bl://）カタログを作成する（推奨）

gcloud biglake iceberg catalogs create CATALOG_ID \
    --project="PROJECT_ID" \
    --catalog-type="biglake" \
    --default-location="DEFAULT_LOCATION" \
    [--restricted-locations="RESTRICTED_LOCATIONS"] \
    [--credential-mode="CREDENTIAL_MODE"] \
    [--primary-location="PRIMARY_LOCATION"]

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

  • CATALOG_ID: Lakehouse ランタイム カタログの ID。
  • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
  • DEFAULT_LOCATION: カタログデータとメタデータのベースとなる Cloud Storage パス（gs://my-bucket/path または gs://my-bucket 形式）。カタログ内のすべての Namespace とテーブルは、このパスの下に配置する必要があります。たとえば、gs://my-bucket/path を指定した場合、gs://my-bucket/another/path の下に Namespace やテーブルをホストすることはできません。
  • RESTRICTED_LOCATIONS: （省略可）許可されている追加のストレージ バケットまたはパスのカンマ区切りのリスト。同様に、パス（gs://my-bucket/path など）を指定すると、そのパスのバケットの下に作成されたすべての名前空間とテーブルがそのパス内に存在する必要があります。セキュリティに関する警告: 認証情報の不正な公開を防ぐため、他のカタログと重複するパスを構成しないでください。詳細については、複数のバケットにまたがるストレージをご覧ください。
  • CREDENTIAL_MODE: 認証方法。エンドユーザー認証情報の場合は end-user、認証情報ベンディング モードの場合は vended-credentials を使用します。
  • PRIMARY_LOCATION: （省略可）BigQuery との互換性を確保するためのカタログのプライマリ リージョン（US や EU など）。

単一バケット（gs://）カタログを作成する

単一バケット（gs://）カタログを作成するには、--catalog-type を gcs-bucket に設定します。

gcloud biglake iceberg catalogs create CATALOG_ID \
    --project="PROJECT_ID" \
    --catalog-type="gcs-bucket" \
    [--credential-mode="CREDENTIAL_MODE"]

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

  • CATALOG_ID: Lakehouse ランタイム カタログの ID。単一バケット（gs://）カタログの場合、これは Cloud Storage バケットの名前に一致する必要があります。
  • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
  • CREDENTIAL_MODE: 認証方法。エンドユーザー認証情報の場合は end-user、認証情報ベンディング モードの場合は vended-credentials を使用します。

REST

Iceberg REST カタログを作成する

REST API を使用してカタログ管理エンドポイントを作成するには、CreateIcebergCatalog エンドポイントに POST リクエストを送信します。

POST /iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs?icebergCatalogId=CATALOG_ID

リクエストの本文には、基盤となる Cloud Storage バケット ウェアハウスや認証モードなど、カタログ構成を定義する IcebergCatalog JSON ペイロードを含める必要があります。

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

  • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
  • CATALOG_ID: Lakehouse ランタイム カタログの ID。