Enable credential vending

Enabling credential vending mode for an existing Apache Iceberg REST catalog configures Lakehouse for Apache Iceberg to vend short-lived, downscoped storage tokens to authorized query engines or workloads.

Within the Lakehouse runtime catalog, this authentication method eliminates the need for you or query runtimes to hold direct read and write permissions on the underlying Cloud Storage bucket.

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 enable credential vending, ask your administrator to grant you the following IAM roles:

  • All:
  • Auto-provisioned Apache Iceberg REST catalog service account: Storage Object User (roles/storage.objectUser) on the target Cloud Storage bucket. After enabling credential vending, explicitly grant the Storage Object User role (roles/storage.objectUser) on your storage bucket to your catalog's auto-provisioned Apache Iceberg REST 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.

Enable credential vending

If the authentication method for your Apache Iceberg REST catalog is set to end-user credentials, you can switch it to credential vending mode.

Console

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

Go to Lakehouse

  1. In the row of the catalog that you're updating, select More catalog actions > Edit authentication.

    1. In the authentication dialog, select Credential vending mode. The auto-provisioned Apache Iceberg REST 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 don't have sufficient scope to perform storage writes.

    2. Select Save. ` Your catalog is updated and the Catalog details page opens.

  2. Under Authentication method, select Set bucket permissions.

    1. In the dialog, select Confirm.

This verifies that your catalog's service account has the Storage Object User role (roles/storage.objectUser) on your storage bucket.

gcloud

Use the gcloud biglake iceberg catalogs create command.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode vended-credentials \
    [--primary-location LOCATION]

Replace the following:

  • CATALOG_NAME: a name for your catalog. This name often matches the Cloud Storage bucket ID used with the Lakehouse Iceberg REST catalog—for example, if your bucket is gs://bucket-id, the catalog name might be bucket-id. This name is also used as the catalog identifier when querying these tables from BigQuery.
  • PROJECT_ID: your Google Cloud project ID.

  • LOCATION: (Optional) The primary region for the catalog to ensure interoperability with BigQuery. For Cloud Storage buckets in the US region (for example, US or us-central1) or the EU region (for example, EU or europe-west4), specify US or EU respectively to ensure the catalog is accessible and available for querying from the corresponding BigQuery multi-regions. For more information, see Bucket and catalog regions.

    After creating the catalog, explicitly grant the Storage Object User role (roles/storage.objectAdmin) on your storage bucket to your catalog's auto-provisioned Apache Iceberg REST catalog service account.

REST

To enable credential vending mode using the REST API, make a PATCH request to the UpdateIcebergCatalog endpoint:

PATCH /iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs/CATALOG_ID?updateMask=icebergCatalog.credentialMode

The request body must contain an IcebergCatalog JSON payload with credentialMode set to VENDED_CREDENTIALS.

Replace the following:

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