Skip to main content

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.

This guide describes how to prepare a Snowflake Open Catalog (Polaris) for use with StreamNative Ursa as an Iceberg catalog on AWS.
Important: Polaris does not support reading buckets from a different region. The StreamNative Ursa cluster, the storage bucket, and the Polaris catalog must all reside in the same AWS region.

​
Prerequisites

  • A Snowflake standard account
  • An AWS account with permissions to create S3 buckets and IAM roles
  • Access to the Snowflake Open Catalog feature (request via your Snowflake account team if not yet enabled)

​
1. Create a Snowflake Open Catalog Account

The Snowflake Open Catalog console requires a dedicated Open Catalog account. From the standard Snowflake console, navigate to Admin -> Accounts and use the toggle to Create Snowflake Open Catalog Account. Snowflake console Create Open Catalog account Configure the account with:
  • Cloud: AWS
  • Region: the region in which your S3 bucket resides (for example, US East (Ohio))
  • Edition: any
Account configuration Provide an admin username and password. Account credentials After creation, click the Account URL to sign in to the Open Catalog console. Account created Open Catalog console

​
2. Create an S3 Bucket

Create an S3 bucket in the same region as the Open Catalog account. Create bucket

​
3. Create an IAM Policy

Navigate to AWS IAM -> Policies -> Create policy. Create policy Paste the following policy, replacing the bucket name and subpath with your values: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:GetObjectVersion",
        "s3:DeleteObject",
        "s3:DeleteObjectVersion"
      ],
      "Resource": "arn:aws:s3:::<your-bucket>/<your-subpath>/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket",
        "s3:GetBucketLocation"
      ],
      "Resource": "arn:aws:s3:::<your-bucket>/<your-subpath>",
      "Condition": {
        "StringLike": {
          "s3:prefix": ["*"]
        }
      }
    }
  ]
}
Policy JSON Policy next step

​
4. Create an IAM Role

Navigate to AWS IAM -> Roles -> Create role and configure:
  • Trusted entity type: AWS account
  • An AWS account: This account
  • Enable External ID with a unique value (you will reference this when creating the Polaris catalog)
Create role Trust settings Attach the policy created in step 4. Attach policy Provide a role name and create the role. Save role Record the role ARN (for example, arn:aws:iam::<account-id>:role/<role-name>). Role ARN

​
5. Create the Polaris Catalog

In the Snowflake Open Catalog console, create a new catalog. Create catalog Configure the catalog with:
  • External: disabled
  • Storage provider: S3
  • Default base location: s3://<your-bucket>/<your-subpath> (the path from step 3)
  • S3 role ARN: the role ARN recorded in step 5
  • External ID: the External ID configured in step 5
Catalog configuration Catalog created Open the catalog details and record the IAM user ARN that Polaris uses to access AWS. You will use this in step 7 to update the trust policy of the IAM role. Catalog IAM user ARN

​
6. Update the IAM Role Trust Policy

Return to the AWS IAM console, open the role created in step 5, and edit the trust relationship. Find role Edit trust policy Update Principal.AWS to the Polaris IAM user ARN recorded in step 6. Update trust policy Click Update policy.

​
7. Create a Connection (Service Principal)

In the Open Catalog console, create a new connection that StreamNative Ursa will use to authenticate. Create connection Configure with:
  • Name: any name
  • Create new principal role: enabled
  • Principal Role Name: any name
Connection configuration After creation, record the Client ID and Client Secret — the secret cannot be retrieved later. Connection credentials

​
8. Create a Catalog Role and Grant Privileges

Navigate to Catalogs -> [your catalog] -> Roles -> + Catalog Role and create a role with the following privileges:
  • NAMESPACE_CREATE
  • NAMESPACE_LIST
  • NAMESPACE_READ_PROPERTIES
  • NAMESPACE_WRITE_PROPERTIES
  • TABLE_LIST
  • TABLE_CREATE
  • TABLE_WRITE_DATA
  • TABLE_READ_DATA
  • TABLE_READ_PROPERTIES
  • TABLE_WRITE_PROPERTIES
Create catalog role Click Grant to Principals Role and grant the catalog role to the principal role created in step 8. Grant to principal role Grant configuration Role bindings For background on the relationship between catalogs, catalog roles, principal roles, and principals, see the Polaris Quick Start.

​
Catalog Information Summary

When the steps above are complete, collect the following values for the StreamNative Ursa compaction service:
ValueDescription
iceberg.uriPolaris REST endpoint (e.g., https://<account>.<region>.aws.snowflakecomputing.com/polaris/api/catalog). The format follows the URL of your Polaris console.
iceberg.warehouseThe Polaris catalog name created in step 6
iceberg.credential<client-id>:<client-secret> from step 8
iceberg.scopePRINCIPAL_ROLE:ALL
For the next steps, see Configure Lakehouse Catalogs.