> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamnative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Unity Catalog for Delta Lake on GCP

This guide describes how to prepare a Databricks Unity Catalog for use with StreamNative Ursa as a Delta Lake catalog on Google Cloud Platform (GCP).

## Prerequisites

* A GCP project with permissions to create GCS buckets and IAM roles
* A Databricks account with permissions to create workspaces

## 1. Create a Databricks Workspace

> Skip this step if you already have the Databricks Workspace in GCP

In the GCP Databricks account console, click **Create workspace**.

![Create workspace](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-01.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=7373cabcb4ea32824708164998899554)

Enter the workspace name, choose the region, and provide your GCP project ID.

![Workspace configuration](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-02.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=29a2c755c4944b40ac4a9137f6ef35dd)

Click **Save**. The workspace status shows **Provisioning** while initialization is in progress.

![Workspace provisioning](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-03.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=f2a16afd42bbf66bad977ca33f85c6df)

When the status changes to **Running**, the workspace is ready.

![Workspace running](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-04.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=ee3ff98f50c8792266fdbc8e602c8201)

Open the workspace to enter the Unity Catalog console.

![Unity Catalog console](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-05.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=391be90e3a0dfa9be592b4e32e8140c8)

## 2. (Recommend) Generate an OAuth2 Service Principal

For OAuth2 authentication, navigate to **Identity and access -> Service principals -> Manage**.

![Service principals](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-10.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=b055f83275f274a5c1ac707fd3f3d655)

Click **Add service principal -> Add new** and provide a name.

![Add service principal](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-11.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=1fd093def40de8db74bef332710c97da)

![Create service principal](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-12.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=83e75d153982777594e6746408d6be2f)

![Service principal created](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-13.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=d172eb21f5a3169cc6762316eefe9c5b)

Open the service principal, click **Secrets -> Generate secret**, choose an expiration period, and **Generate**.

![Generate secret](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-14.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=b2ec63d4d8d33871499ac06743b1814e)

Record both the **Client ID** and **Client Secret** -- the secret cannot be retrieved later.

![Client ID and Secret](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-15.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=ac43e302ebd693deca3f8c64655760b8)

## 3. (Alternative) Generate a User Token

A Databricks user token can be used by StreamNative Ursa to authenticate against Unity Catalog.

Open **User Settings**.

![User settings](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-06.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=c60b5f0c9c40852cda7e1061d4e95243)

Navigate to **Developer -> Access tokens -> Manage** and generate a new token. Record the token value -- it cannot be retrieved later.

![Developer menu](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-07.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=09968bd9cba0f6e1b34aad19808c47bd)

![Access tokens](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-08.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=15359390472944f29ed50537fa79f490)

![Generate token](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-09.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=23aa0ec21b591904b2eb383044942d8f)

## 4. Configure Unity Catalog Access

Navigate to **Catalog -> Settings -> Metastore**.

![Catalog settings](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-16.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=51fbb40f005acde96513398a4fb12cf6)

Enable **External data access** on the metastore.

![External data access](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-17.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=760534ec3443e23a5a45a0aa2eb4bda6)

Grant catalog privileges with the following settings:

* **Principal:** All accounts (or the specific user/service principal)
* **Privilege presets:** Data Editor (selects related privileges automatically)
* **EXTERNAL USE SCHEMA:** Enabled

![Grant privileges](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-18.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=4704bac807cb49816033b3d4c67ad6ab)

![Privilege configuration](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-19.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=3edc422b82d32e1a2707ac840b70ed85)

## 5. Grant Bucket Permissions to the Databricks Service Account

When the Databricks workspace is initialized, a service account is created for Unity Catalog.

Navigate to **Catalog -> Settings -> Credentials** to find the service account.

![Credentials menu](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-27.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=fc3b2211034f57eec5ddad032b99df9e)

Example service account name:

```
db-uc-credential-<id>@uc-uswest1.iam.gserviceaccount.com
```

![Databricks service account](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-28.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=5f5dfae5d5510768a3296e8d730fc385)

### 5.1 Create a Custom IAM Role

In the GCP console, navigate to **IAM & Admin -> Roles -> Create role** and add the following permissions:

* `storage.buckets.get`
* `storage.objects.create`
* `storage.objects.delete`
* `storage.objects.get`
* `storage.objects.list`

![Create role](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-29.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=1a0f093e43f6ce91d4b592a390704472)

![Role setup](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-30.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=f2075f5e4c81c55bb90b295e0706d6e8)

![Permissions](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-31.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=d6028becd461ac2241d94cb70a5c45c0)

![Permissions selected](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-32.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=cdc0d6db2e0d843514ca17908ac2aec8)

### 5.2 Assign the Role to the Databricks Service Account

Open your bucket, click **PERMISSIONS -> View BY PRINCIPALS -> GRANT ACCESS**.

![Grant bucket access](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-33.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=179c11b211eb9bf19675f6fd1d850b90)

Add the Databricks service account, select the role created in step 6.1, and click **SAVE**.

![Save access](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-34.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=89a1371d06534c65711ebd44f291aa46)

## 6. Create an External Location in Unity Catalog

Navigate to **Catalog -> Settings -> External Locations** and create a new external location.

![External locations](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-35.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=851d5cd5891f188280cd39a351f6871a)

![Create external location](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-36.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=f30c46392d0fc0fa9f50c55952e74f54)

Configure with:

* **External location name:** any name
* **URL:** the GCS bucket path
* **Storage credential:** the Unity Catalog credential

![External location form](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-37.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=6919653db0b21ac7aabf0ae197aacc96)

Click **Test connection** to verify access.

![External location created](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-38.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=0c6e342b007b4b5f38bee069537e8615)

Grant **ALL PRIVILEGES** on the external location to the service principal.

![Grant OAuth2 permissions](https://mintcdn.com/streamnative/X17SyiKppfiqQD9i/images/ursa-lakehouse/uc-delta-gcp-39.webp?fit=max\&auto=format\&n=X17SyiKppfiqQD9i\&q=85\&s=414e96212dbc5afe81cd9ba3f152d530)

## Catalog Information Summary

When the steps above are complete, collect the following values for the StreamNative Ursa compaction service:

| Value | Description |
| - | - |
| `unityCatalogUri` | Databricks workspace URL (e.g., `https://<workspace>.gcp.databricks.com`) |
| `unityCatalogName` | The Unity Catalog name |
| `unityCatalogToken` | Personal access token from step 2, **or** |
| `unityCatalogClientId` / `unityCatalogClientSecret` | OAuth2 credentials from step 3 |

For the next steps, see [Register Lakehouse Catalogs](https://docs.streamnative.io/cloud/lakehouse/catalogs/register-catalog.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.