For the complete documentation index, see llms.txt. This page is also available as Markdown.

Storage Integration Setup

Set up a Snowflake storage integration and external stage so Espresso can receive your usage metadata exports.

Set up a storage integration and named external stage in your Snowflake account so Espresso can write your usage metadata exports to Espresso's S3 bucket. No credentials are exchanged.

Values

Find these on the Proxy Onboarding page of the Espresso dashboard:

Value
Example

<SLUG>

Your Espresso internal identifier

External ID

<EXTERNAL_ID>

Your bucket path is s3://apricot-snowflake-unload/prod/<SLUG>/.

Information you need:

Value
Notes

<YOUR_AWS_ACCOUNT_ID>

The AWS account the IAM role will live in

<ESPRESSO_ROLE>

The Snowflake role your Espresso service user uses

The steps below create an IAM role EspressoUnloadRole, a storage integration ESPRESSO_UNLOAD, and a stage ESPRESSO.INTEGRATIONS.ESPRESSO_UNLOAD_STAGE. Rename them if your conventions require it.

Before you start

The integration needs the IAM role to exist, and the role's trust policy needs values that only exist once the integration is created. So the role is created with a placeholder trust policy in step 1 and finalized in step 4.

Step 1 — Create the IAM role

cat > trust-placeholder.json <<'JSON'
{"Version": "2012-10-17", "Statement": [{
  "Effect": "Allow",
  "Principal": {"AWS": "arn:aws:iam::<YOUR_AWS_ACCOUNT_ID>:root"},
  "Action": "sts:AssumeRole"
}]}
JSON

aws iam create-role --role-name EspressoUnloadRole \
  --assume-role-policy-document file://trust-placeholder.json

Step 2 — Attach the S3 permissions policy

Send the role ARN to Espresso now. We authorize it on our side, and that has to be in place before the step 6 check will pass.

Step 3 — Create the storage integration

  • STORAGE_ALLOWED_LOCATIONS pins the integration to that path.

  • Use the External ID from the Proxy Onboarding page rather than letting Snowflake generate one, so it stays stable. If you later run CREATE OR REPLACE, keep the same value or step 4 has to be redone.

  • STORAGE_AWS_OBJECT_ACL is required for the cross-account write.

Step 4 — Finalize the role's trust policy

Copy STORAGE_AWS_IAM_USER_ARN from the output.

IAM changes are eventually consistent. If step 6 fails with Access Denied, retry shortly.

Step 5 — Create the stage and grant access

Step 6 — Verify

A row count in the response means the integration, stage, trust policy, and authorization are all correct.

Step 7 — Confirm with Espresso

Let us know the check in step 6 passed, and that the stage is ESPRESSO.INTEGRATIONS.ESPRESSO_UNLOAD_STAGE. We handle the rest.

Troubleshooting

Symptom
Cause

Access Denied on step 6

Trust policy still propagating, or Espresso hasn't authorized the role ARN yet

SQL access control error on the stage

Missing GRANT USAGE ON INTEGRATION

Access Denied after a working setup

The integration was recreated and its External ID changed — redo step 4

Files written but Espresso reports missing data

STORAGE_AWS_OBJECT_ACL omitted from step 3

Last updated