The Lakehouse runtime catalog lets you enable credential vending mode
for [catalog endpoints](https://docs.cloud.google.com/lakehouse/docs/about-lakehouse-catalogs.md.txt#configuration)
in borderless Lakehouse.

Credential vending mode vends short-lived, downscoped storage tokens to
authorized query engines and workloads. This authentication method eliminates
the need for you or query runtimes to hold direct read and write permissions on
the underlying Cloud Storage bucket.

> [!NOTE]
> **Note:** You can enable credential vending mode only for Apache Iceberg REST catalog endpoints; it isn't supported for Apache Hive catalog endpoints.

## Before you begin

1. Read [About the Lakehouse runtime catalog](https://docs.cloud.google.com/lakehouse/docs/about-lakehouse-catalogs.md.txt) to understand how the Lakehouse runtime catalog works and the limitations for the service.

### Required roles


To get the permissions that
you need to enable credential vending,

ask your administrator to grant you the
following IAM roles:

- All:
  - [BigLake Admin](https://docs.cloud.google.com/iam/docs/roles-permissions/biglake.md.txt#biglake.admin) (`roles/biglake.admin`) on your project
  - [Storage Admin](https://docs.cloud.google.com/iam/docs/roles-permissions/storage.md.txt#storage.admin) (`roles/storage.admin`) on your project
- Auto-provisioned Apache Iceberg REST catalog service account: [Storage Object User](https://docs.cloud.google.com/iam/docs/roles-permissions/storage.md.txt#storage.objectUser) (`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](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

> [!NOTE]
> **Note:** Creation of the auto-provisioned catalog service account is [eventually consistent](https://wikipedia.org/wiki/Eventual_consistency). This means that it takes time for the service account to propagate through the system. If you try to grant roles to the service account immediately after creation, the request might fail. To learn how long it takes, on average, for access changes to propagate, see [Access change propagation](https://docs.cloud.google.com/iam/docs/access-change-propagation.md.txt).

If the Cloud Storage buckets associated with your catalog endpoint are
protected by a VPC Service Controls service perimeter, then you must also configure
an ingress rule for the catalog service account. For more
information, see
[Use VPC Service Controls with credential vending](https://docs.cloud.google.com/lakehouse/docs/credential-vending.md.txt#vpc-sc).

## Enable credential vending

If the authentication method for your Apache Iceberg REST catalog endpoint is set
to end-user credentials, you can switch it to [credential vending
mode](https://docs.cloud.google.com/lakehouse/docs/credential-vending).

### Console

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

[Go to Lakehouse](https://console.cloud.google.com/biglake)

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

   ```console
     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](https://docs.cloud.google.com/sdk/gcloud/reference/biglake/iceberg/catalogs/update.md.txt).

```bash
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](https://docs.cloud.google.com/sdk/gcloud/reference/biglake/iceberg/catalogs/update.md.txt).
- `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`](https://docs.cloud.google.com/lakehouse/docs/reference/rest/v1/iceberg.v1.restcatalog.extensions.projects.catalogs/patch.md.txt) endpoint:

    PATCH /iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs/CATALOG_ID?updateMask=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.