カタログを作成

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

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

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

始める前に

  1. Lakehouse ランタイム カタログについてを読んで、Lakehouse ランタイム カタログの仕組みとサービスの制限事項を理解してください。
    2. アカウントにログインします。 Google Cloud を初めて使用する場合は、 アカウントを作成して、 実際のシナリオでプロダクトがどのように機能するかを評価してください。 Google Cloud新規のお客様には、ワークロードの実行、テスト、デプロイに利用できる $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.tables.register）が必要です。この権限は BigLake 管理者ロールに含まれています。
  • 認証情報ベンディング モードで自動プロビジョニングされたカタログ サービス アカウントを使用する: Storage オブジェクト ユーザー （roles/storage.objectUser） ターゲット Cloud Storage バケットに対する。カタログを作成したら、ストレージ バケットに対する Storage オブジェクト ユーザーロール（roles/storage.objectUser）を自動プロビジョニングされたサービス アカウントに明示的に付与します。

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

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

カタログを作成

カタログを作成します。

コンソール

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

シングルバケット（gs://）カタログを作成する

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

    Lakehouse に移動

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

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

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

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

    • [Iceberg REST カタログ] を選択した場合は、カタログタイプに [Cloud Storage バケット] を選択し、カタログで使用する Cloud Storage バケットを選択します。
    • [Hive カタログ] を選択した場合は、一意のカタログ名を入力し、関連する 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 の形式）。カタログ内のすべての名前空間とテーブルは、このパスの下に配置する必要があります。たとえば、gs://my-bucket/path を指定した場合、gs://my-bucket/another/path の下に名前空間やテーブルをホストすることはできません。
  • 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 を使用してカタログ管理エンドポイントを作成するには、POST リクエストを CreateIcebergCatalog エンドポイントに送信します。

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。