Create a catalog

Creating a catalog (such as an Apache Iceberg REST catalog or Apache Hive catalog) establishes a management endpoint within the Lakehouse runtime catalog. This endpoint points to an underlying Cloud Storage warehouse bucket, providing a metadata layer that lets query engines and open-source workloads interact directly with your tables.

When creating your catalog for Lakehouse for Apache Iceberg, you can choose between end-user credentials or credential vending mode for storage access delegation.

Before you begin

  1. Verify that billing is enabled for your Google Cloud project.

  2. 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

Required roles

To get the permissions that you need to create a catalog, ask your administrator to grant you the following IAM roles:

  • All:
  • Auto-provisioned Lakehouse runtime catalog service account in credential vending mode: Storage Object User (roles/storage.objectUser) on the target Cloud Storage bucket. After creating the catalog, explicitly grant the Storage Object User role (roles/storage.objectUser) on your storage bucket to your catalog's auto-provisioned Lakehouse runtime catalog service account.

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Create a catalog

Create a catalog endpoint.

Console

  1. In the Google Cloud console, open the Lakehouse page.

    Go to Lakehouse

  2. Select Create catalog. The Create catalog page opens.

  3. Select the catalog type:

    • To create an Apache Iceberg REST catalog, select Iceberg REST catalog.
    • To create an Apache Hive catalog, select Hive catalog.

  4. For Select a Cloud Storage bucket, enter the name of the Cloud Storage bucket to use with your catalog. Alternatively, select Browse to choose from a list of existing buckets or to create one. You can only have one catalog per Cloud Storage bucket.

  5. For Authentication method, select either End-user credentials or Credential vending mode.

    If you select Credential vending mode, the auto-provisioned Lakehouse runtime catalog service account requires the explicit Storage Object User role (roles/storage.objectUser) on the target Cloud Storage bucket. By default, it is created with viewer-only access. Without this role, vended credentials do not have sufficient scope to perform storage writes.

  6. Select Create.

    Your catalog is created and the Catalog details page opens.

  7. Under Authentication method, select Set bucket permissions.

  8. In the dialog, select Confirm.

    This verifies that your catalog's service account has the Storage Object Admin role on your storage bucket. If you create catalogs using gcloud or Terraform, you must grant this role manually.

REST

To create a catalog management endpoint using the REST API, make a POST request to the CreateIcebergCatalog endpoint:

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

The request body must contain an IcebergCatalog JSON payload defining the catalog configuration, such as the underlying Cloud Storage bucket warehouse and authentication mode.

Replace the following:

  • PROJECT_ID: your Google Cloud project ID.
  • CATALOG_ID: the ID of your Lakehouse runtime catalog.