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:
<SLUG>
Your Espresso internal identifier
External ID
<EXTERNAL_ID>
Your bucket path is s3://apricot-snowflake-unload/prod/<SLUG>/.
Information you need:
<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.jsonStep 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_LOCATIONSpins 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_ACLis 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
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