> ## 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 Managed Iceberg Table on GCP

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

## Prerequisites

* A Databricks workspace on GCP with Unity Catalog and Iceberg Managed Table enabled
* A GCP project with permissions to create GCS buckets

## 1. Create a GCS Bucket

Create a GCS bucket to use as the Unity Catalog storage location (for example, `unity-catalog-iceberg-bucket`).

> **Important:** The bucket must be located in the **same region** as your Databricks workspace and your StreamNative Ursa cluster. Cross-region access introduces additional network traffic and latency.

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-01.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=a95fe49bd599c6e6bdd6566ec7e2d5de" alt="Create GCS bucket" width="1920" height="1288" data-path="images/ursa-lakehouse/uc-iceberg-gcp-01.webp" />

For additional details, see the [Databricks GCP Unity Catalog documentation](https://docs.databricks.com/gcp/en/data-governance/unity-catalog/create-metastore).

## 2. Create a Storage Credential in Unity Catalog

In the Databricks Catalog console, create a new storage credential. Databricks generates a service account that needs permissions on the bucket.

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-02.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=2c1a769444e181b790676700ada586f4" alt="Create credential" width="1920" height="916" data-path="images/ursa-lakehouse/uc-iceberg-gcp-02.webp" />

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-03.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=aaabe4256e782ee159a3c69bbc2291c1" alt="Credential form" width="1920" height="1140" data-path="images/ursa-lakehouse/uc-iceberg-gcp-03.webp" />

After creation, record the generated service account name. Example:

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

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-04.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=771e588e0acfe4e27c390cd6d77200e9" alt="Generated service account" width="1920" height="986" data-path="images/ursa-lakehouse/uc-iceberg-gcp-04.webp" />

## 3. Grant GCS Permissions to the Service Account

In the GCP console, navigate to the bucket's **Permissions** tab and click **Grant access**.

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-05.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=84a4abc7977c33d2b32e4e61fff4b64c" alt="Grant access" width="1920" height="1079" data-path="images/ursa-lakehouse/uc-iceberg-gcp-05.webp" />

Grant the following roles to the service account from step 2:

* **Storage Legacy Bucket Reader**
* **Storage Object Admin**

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-06.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=9df62d9a5ff6bcebfaeed5947568ae48" alt="Assign storage roles" width="1920" height="986" data-path="images/ursa-lakehouse/uc-iceberg-gcp-06.webp" />

## 4. Create the External Location

In the Databricks Catalog console, create an external location with the following settings:

* **External location name:** any name
* **URL:** the GCS bucket path created in step 1
* **Storage credential:** the credential created in step 2

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-07.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=be971755f988235ba82221324245cf26" alt="Create external location" width="1920" height="680" data-path="images/ursa-lakehouse/uc-iceberg-gcp-07.webp" />

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-08.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=6ac9867ffb1aa21af4c1c26df0ae4603" alt="External location settings" width="1920" height="1106" data-path="images/ursa-lakehouse/uc-iceberg-gcp-08.webp" />

Use **Test connection** to verify the credential has sufficient permissions.

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-09.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=9ddb5543c596eb124d45a6c8fbcd0309" alt="Test connection" width="1920" height="822" data-path="images/ursa-lakehouse/uc-iceberg-gcp-09.webp" />

## 5. Create the Unity Catalog

Create a new Catalog with:

* **Type:** Standard
* **Storage location:** the external location created in step 4 (a sub-path within this location may be specified)

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-10.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=0c37230ba22cf83bb1b1f43a7c133905" alt="Create catalog" width="1920" height="636" data-path="images/ursa-lakehouse/uc-iceberg-gcp-10.webp" />

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-11.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=4825e6638f968a42d4e5088c829c20f1" alt="Catalog form" width="1920" height="1067" data-path="images/ursa-lakehouse/uc-iceberg-gcp-11.webp" />

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-12.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=e7c4a8c4956cd07ec6ff33621ff1f8a8" alt="Catalog created" width="1920" height="711" data-path="images/ursa-lakehouse/uc-iceberg-gcp-12.webp" />

## 6. Grant Catalog Permissions

Grant permissions on the catalog. The `EXTERNAL_USE_SCHEMA` permission is **required** for Iceberg Managed Tables in Unity Catalog.

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-13.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=9b24a5943524d31d38bf334a1a35a7f0" alt="Grant catalog permissions" width="1920" height="705" data-path="images/ursa-lakehouse/uc-iceberg-gcp-13.webp" />

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-14.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=fdbe948d3ae03c5df889f76f16b09a16" alt="EXTERNAL_USE_SCHEMA permission" width="1920" height="1089" data-path="images/ursa-lakehouse/uc-iceberg-gcp-14.webp" />

## 7. Enable External Data Access on the Metastore

> **Note:** This action requires **Databricks Account Admin** privileges; without them, the **Metastore** entry is not visible.

Enable **External data access** on the metastore. This step is **required** for Unity Catalog Iceberg Managed Tables.

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-15.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=7b93978e0e01b385ef09dabddae53d9b" alt="External data access" width="1920" height="806" data-path="images/ursa-lakehouse/uc-iceberg-gcp-15.webp" />

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-16.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=657d742fbae70a1195cbf624927911ec" alt="External data access enabled" width="1920" height="963" data-path="images/ursa-lakehouse/uc-iceberg-gcp-16.webp" />

## 8. Create OAuth2 Credentials

Create an OAuth2 service principal that StreamNative Ursa will use to authenticate.

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-17.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=a8864cfcdd30fe883c010948093330a7" alt="OAuth2 setup" width="1920" height="951" data-path="images/ursa-lakehouse/uc-iceberg-gcp-17.webp" />

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-18.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=fbe5703c7fabde5b01ffe115cfb5e606" alt="OAuth2 setup" width="1920" height="760" data-path="images/ursa-lakehouse/uc-iceberg-gcp-18.webp" />

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-19.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=af0c96d3c4cabbee45f0759941ac42c3" alt="OAuth2 setup" width="1920" height="731" data-path="images/ursa-lakehouse/uc-iceberg-gcp-19.webp" />

Generate a secret for the principal and record both the **Client ID** and **Client Secret**.

<img src="https://mintcdn.com/streamnative/x2q9Vy9571owFXU5/images/ursa-lakehouse/uc-iceberg-gcp-20.webp?fit=max&auto=format&n=x2q9Vy9571owFXU5&q=85&s=1bf8ce1c8e50255e71816ed5a17c906c" alt="Generate secret" width="1920" height="710" data-path="images/ursa-lakehouse/uc-iceberg-gcp-20.webp" />

## Catalog Information Summary

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

| Value      | Description                                                                                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------ |
| URI        | Databricks workspace URL (e.g., `https://<workspace>.gcp.databricks.com/api/2.1/unity-catalog/iceberg-rest`) |
| Warehouse  | The Unity Catalog name created in step 5                                                                     |
| Credential | `<client-id>:<client-secret>` from step 8                                                                    |

For the next steps, see [Configure Lakehouse Catalogs](../../../configure-lakehouse-catalogs).
