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 all associated Cloud Storage buckets. After enabling credential vending, explicitly grant the Storage Object User role (roles/storage.objectUser) on all associated storage buckets 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.

  2. 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 all associated Cloud Storage buckets. By default, it has no access. Without this role, vended credentials don't have sufficient scope to perform storage writes.

  3. Select Save.

      Your catalog is updated and the **Catalog details** page opens.

  4. Under Authentication method, select Set bucket permissions.

  5. In the dialog, select Confirm.

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

gcloud

Use the gcloud biglake iceberg catalogs update command.

gcloud biglake iceberg catalogs update \
    CATALOG_NAME \
    --project PROJECT_ID \
    --credential-mode vended-credentials

Replace the following:

  • CATALOG_NAME: a name for your catalog. For Lakehouse catalogs, this is your custom catalog name. For Cloud Storage bucket catalogs, this matches the Cloud Storage bucket ID used with the REST catalog. This name is also used as the catalog identifier when querying these tables from BigQuery.

  • PROJECT_ID: your Google Cloud project ID.

    After enabling credential vending, explicitly grant the Storage Object User role (roles/storage.objectUser) on all associated storage buckets 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.credential_mode

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

Replace the following:

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