Credential vending overview

Credential vending mode in the Lakehouse runtime catalog lets you delegate Cloud Storage access to query engines and enforce fine-grained Identity and Access Management (IAM) policies at the catalog, namespace, and table levels for Apache Iceberg tables. Instead of granting direct bucket permissions, you configure the Apache Iceberg REST catalog endpoint to vend short-lived, downscoped storage tokens for authorized table paths. This mode is also required for automatic table management.

When to use credential vending

The following are some common use cases:

  • Enforce table-level access without bucket-level roles: grant analysts and workloads access to specific Apache Iceberg tables while preventing direct access to underlying Cloud Storage buckets or sibling table directories.
  • Centralize access governance across multiple query engines: apply consistent IAM policies across BigQuery, Managed Service for Apache Spark, open-source Apache Spark, and Trino using short-lived, path-scoped tokens.
  • Isolate warehouse buckets inside a service perimeter: store table data in Cloud Storage buckets protected by VPC Service Controls while authorizing storage reads and writes through a single catalog endpoint service account.

How credential vending works

When you use credential vending mode, the sequence of operations enforces IAM policies before storage is accessed. The following diagram illustrates how query engines obtain downscoped storage tokens from the Lakehouse runtime catalog to securely read and write data directly in Cloud Storage:

Query engines obtain downscoped storage tokens from the Lakehouse runtime catalog to read and write data in Cloud Storage.
Credential vending workflow delegating Cloud Storage access.

The sequence of operations shown in the preceding diagram is as follows:

  1. Request: A user submits a SQL statement, such as a query, DML, or DDL operation, to a supported engine, such as Spark or BigQuery.
  2. Metadata lookup: The engine sends a request to the Lakehouse runtime catalog to resolve the table.
  3. Authentication and policy: The Lakehouse runtime catalog authenticates the user and checks their IAM permissions on Lakehouse resources.
  4. Response: Because credential vending mode is enabled, the Lakehouse runtime catalog returns the metadata and a short-lived storage token (downscoped storage credentials) to the engine. The token is scoped to the paths associated with the table and downscoped to the minimum required permissions (for example, read-only access for queries that don't need to write files).
  5. Access: The engine uses this token to read or write the specific authorized files directly from Cloud Storage.
  6. Compute: The engine processes the data or executes the operation, and returns the results.

When automatic table management (gcp.biglake.table-management.enabled) is enabled, background maintenance tasks such as compaction, snapshot expiration, and garbage collection use the catalog's auto-provisioned service account to authenticate directly to Cloud Storage and update the underlying data files.

Supported engines

To use credential vending with query engines, you must configure the Apache Iceberg REST catalog endpoint in your Lakehouse runtime catalog in credential vending mode. Credential vending isn't supported for Apache Hive catalog endpoints.

  • Open-source engines: Supported engines such as Spark and Trino use short-lived storage tokens vended by the Lakehouse runtime catalog. Your client application must specify support for credential vending in the X-Iceberg-Access-Delegation header.
  • BigQuery: BigQuery uses vended credentials for Cloud Storage access instead of end-user credentials.

Required service account permissions

When credential vending mode is enabled, ensure that the following service accounts have the necessary roles:

  • Auto-provisioned catalog endpoint service account: You must grant the Storage Object User role (roles/storage.objectUser) to this account on all associated Cloud Storage buckets. Without this access, vended credentials can't read or write to storage. If you use the Google Cloud console, clicking Set bucket permissions verifies this role. For the Google Cloud CLI, Terraform, or the REST API, you must grant this role manually.
  • Query engine service accounts: Service accounts running query engine jobs (such as Managed Service for Apache Spark or Dataflow) require the BigLake Editor role (roles/biglake.editor) to obtain vended credentials with write scope.

Use VPC Service Controls with credential vending

When you use the Apache Iceberg REST catalog endpoint in credential vending mode with Cloud Storage buckets inside a VPC Service Controls service perimeter, you can support the following use cases:

  • Create and modify Apache Iceberg tables in protected buckets: run CREATE TABLE or DML statements from BigQuery, Managed Service for Apache Spark, Spark, or Trino when warehouse buckets reside inside a service perimeter.
  • Delegate fine-grained table reads inside a storage perimeter: enforce table-level IAM policies using short-lived, downscoped storage tokens without granting end users or query runtimes direct IAM roles on perimeter-protected buckets.

In credential vending mode, query engines and Lakehouse authenticate to Cloud Storage using credentials issued for the catalog endpoint's auto-provisioned service account (blirc-PROJECT_NUMBER-ID@gcp-sa-biglakerestcatalog.iam.gserviceaccount.com). Because this service agent belongs to a Google-managed project outside your service perimeter, Cloud Storage evaluates requests authenticated with its credentials as perimeter ingress whenever the bucket project's perimeter restricts storage.googleapis.com. This evaluation applies even when the catalog endpoint, query job, and bucket are in the same project and service perimeter.

To allow access, configure an ingress rule in Access Context Manager on the perimeter that protects the bucket project with the following settings:

  • Source identity: serviceAccount:blirc-PROJECT_NUMBER-ID@gcp-sa-biglakerestcatalog.iam.gserviceaccount.com
  • Target project: The bucket project (projects/BUCKET_PROJECT_NUMBER)
  • Service: storage.googleapis.com with all methods ('*'), or specific supported service methods

The following ingress.yaml example allows the catalog endpoint's service account to access storage.googleapis.com in the bucket project:

- ingressFrom:
    identities:
    - serviceAccount:CATALOG_ENDPOINT_SERVICE_ACCOUNT
    sources:
    - accessLevel: '*'
  ingressTo:
    operations:
    - serviceName: storage.googleapis.com
      methodSelectors:
      - method: '*'
    resources:
    - projects/BUCKET_PROJECT_NUMBER

Replace the following:

  • CATALOG_ENDPOINT_SERVICE_ACCOUNT: your catalog endpoint's auto-provisioned service account email address (blirc-PROJECT_NUMBER-ID@gcp-sa-biglakerestcatalog.iam.gserviceaccount.com). To retrieve this email address, describe the catalog endpoint:

    gcloud biglake iceberg catalogs describe CATALOG_ID \
    --project=PROJECT_ID \
    --format='value(biglake-service-account)'

    In this command, CATALOG_ID is the ID of your catalog endpoint and PROJECT_ID is the ID of the project that contains the catalog endpoint.

  • BUCKET_PROJECT_NUMBER: the numeric project number of the project that contains the Cloud Storage bucket.

If a table creation or query request is blocked by VPC Service Controls, then the error message includes a vpcServiceControlsUniqueIdentifier value. Search Policy Denied audit logs in Cloud Audit Logs by matching protoPayload.metadata.vpcServiceControlsUniqueId to that identifier, and inspect ingressViolations for the blirc-... principal. For more information, see Retrieve VPC Service Controls errors from audit logs.

What's next