Configure an external volume for Amazon S3¶

Step 1: Create an IAM policy that grants access to your S3 location¶

To configure access permissions for Snowflake in the AWS Management Console, do the following:

1. Log in to the AWS Management Console.

2. From the home dashboard, search for and select IAM.

3. From the left-hand navigation pane, select Account settings.

4. Under Security Token Service (STS) in the Endpoints list, find the Snowflake region where your account is located. If the STS status is inactive, move the toggle to Active.

5. From the left-hand navigation pane, select Policies.

6. Select Create Policy.

7. For Policy editor, select JSON.

8. Add a policy to provide Snowflake with the required permissions to read and write data to your S3 location. The following example policy grants access to all locations in the specified bucket.

   Note

   • Replace bucket with your actual bucket name. You can also specify a path in the bucket; for example, bucket/path.

   • Setting the "s3:prefix": condition to ["*"] grants access to all prefixes in the specified bucket; setting it to ["path/*"] grants access to a specified path in the bucket.

   • For buckets in government regions, the bucket ARNs use the arn:aws-us-gov:s3::: prefix.

   {
      "Version": "2012-10-17",
      "Statement": [
            {
               "Effect": "Allow",
               "Action": [
                  "s3:PutObject",
                  "s3:GetObject",
                  "s3:GetObjectVersion",
                  "s3:DeleteObject",
                  "s3:DeleteObjectVersion"
               ],
               "Resource": "arn:aws:s3:::<bucket>/*"
            },
            {
               "Effect": "Allow",
               "Action": [
                  "s3:ListBucket",
                  "s3:GetBucketLocation"
               ],
               "Resource": "arn:aws:s3:::<bucket>",
               "Condition": {
                  "StringLike": {
                        "s3:prefix": [
                           "*"
                        ]
                  }
               }
            }
      ]
   }
   

   Copy

9. Select Next.

10. Enter a Policy name (for example, snowflake_access) and an optional Description.

11. Select Create policy.

Step 2: Create an IAM role¶

Create an AWS IAM role to grant privileges on the S3 bucket containing your data files.

1. From the left-hand navigation pane in the Identity and Access Management (IAM) Dashboard, select Roles.

2. Select Create role.

3. For the trusted entity type, select AWS account.

4. Under An AWS account, select This account. In a later step, you modify the trusted relationship and grant access to Snowflake.

5. Select the Require external ID option. Enter an external ID of your choice. For example, iceberg-table-external-id.

   An external ID is used to grant access to your AWS resources (such as S3 buckets) to a third party like Snowflake.

6. Select Next.

7. Select the policy that you created in Step 1, which grants access to your S3 location, then select Next.

8. Enter a Role name and description for the role, then select Create role.

   You have now created an IAM policy for an S3 location, created an IAM role, and attached the policy to the role.

9. On the role summary page, locate and record the ARN (Amazon Resource Name) value for the role.

Step 3: Grant privileges required for SSE-KMS encryption to the IAM role (optional)¶

If you want to upload an object encrypted with an AWS KMS key to Amazon S3, the IAM role that you created in Step 2 needs kms:GenerateDataKey permissions on the key. If you want to download an object encrypted with an AWS KMS key, the IAM role needs kms:Decrypt permissions on the key.

If you want to use a KMS key for your server-side encryption, follow these steps to create a key and reference it.

1. In the AWS Management Console, go to the Key Management Service (KMS). From the left navigation, select Customer managed keys, and then select Create key. You must create a key in the same region as your bucket.

2. Create a Symmetric key type. For the key usage, select Encrypt and decrypt. Select Next.

3. For Alias, enter a name for the key and select Next.

4. If needed, select an administrator for the key and select Next.

5. For Define key usage permissions, select your IAM role, then select Next.

6. Review the key configuration details, then select Finish to create the key.

7. Find the key in the list of customer managed keys, select it, and record its ARN. The following is an example of an ARN for a key: arn:aws:kms:us-west-2:111111122222:key/1a1a11aa-aa1a-aaa1a-a1a1-000000000000.

   When you create your external volume, set the KMS_KEY_ID value to the ARN of your key.

Step 4: Create an external volume in Snowflake¶

Create an external volume using the CREATE EXTERNAL VOLUME command.

The following example creates an external volume that defines a single Amazon S3 storage location with encryption. The command specifies the external ID (iceberg-table-external-id) associated with the IAM role created in Step 2. Specifying an external ID lets you use the same IAM role (and external ID) across multiple external volumes.

CREATE OR REPLACE EXTERNAL VOLUME exvol
   STORAGE_LOCATIONS =
      (
         (
            NAME = 'my-s3-us-west-2'
            STORAGE_PROVIDER = 'S3'
            STORAGE_BASE_URL = 's3://MY_EXAMPLE_BUCKET/'
            STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/myrole'
            STORAGE_AWS_EXTERNAL_ID = 'iceberg-table-external-id'
            ENCRYPTION=(TYPE='AWS_SSE_KMS' KMS_KEY_ID='arn:aws:kms:us-west-2:111111122222:key/1a1a11aa-aa1a-aaa1a-a1a1-000000000000')
         )
      );

Step 5: Retrieve the AWS IAM user for your Snowflake account¶

1. Retrieve the ARN for the AWS IAM user that was created automatically for your Snowflake account using the DESCRIBE EXTERNAL VOLUME command. Specify the name of the external volume that you created in Step 4.

   For example:

   DESC EXTERNAL VOLUME exvol;
   

   Copy

2. Record the value for the STORAGE_AWS_IAM_USER_ARN property, which is the AWS IAM user created for your Snowflake account; for example, arn:aws:iam::123456789001:user/abc1-b-self1234.

   Snowflake provisions a single IAM user for your entire Snowflake account. All S3 external volumes in your account use that IAM user.

   Note

   If you didn’t specify an external ID (STORAGE_AWS_EXTERNAL_ID) when you created an external volume, Snowflake generates an ID for you to use. Record the value so that you can update your IAM role trust policy with the generated external ID.

Step 6: Grant the IAM user permissions to access bucket objects¶

In this step, you configure permissions that allow the IAM user for your Snowflake account to access objects in your S3 bucket.

1. Log in to the AWS Management Console.

2. From the home dashboard, search for and select IAM.

3. From the left-hand navigation pane, select Roles.

4. Select the IAM role that you created in Step 2.

5. Select the Trust relationships tab.

6. Select Edit trust policy.

7. Modify the policy document with the DESC EXTERNAL VOLUME output values that you recorded.

   Where:

   • snowflake_user_arn is the STORAGE_AWS_IAM_USER_ARN value you recorded.

   • snowflake_external_id is your external ID. If you already specified an external ID when you created the role, and used the same ID to create your external volume, leave the value as-is. Otherwise, update sts:ExternalId with the value that you recorded.

   Policy document for IAM role

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "",
         "Effect": "Allow",
         "Principal": {
           "AWS": "<snowflake_user_arn>"
         },
         "Action": "sts:AssumeRole",
         "Condition": {
           "StringEquals": {
             "sts:ExternalId": "<snowflake_external_id>"
           }
         }
       }
     ]
   }
   

   Copy

   Note

   You must update this policy document if you create a new external volume (or recreate an existing external volume using the CREATE OR REPLACE EXTERNAL VOLUME syntax) and don’t provide your own external ID. For security reasons, a new or recreated external volume has a different external ID and cannot resolve the trust relationship unless you update this trust policy.

8. Select Update policy to save your changes.

Minimum AWS access control requirements¶

To access files in your S3 bucket, Snowflake requires the following permissions to perform actions on your S3 location:

• s3:DeleteObject

• s3:DeleteObjectVersion

• s3:GetBucketLocation

• s3:GetObject

• s3:GetObjectVersion

• s3:ListBucket

• s3:PutObject

As a best practice, Snowflake recommends that you create a designated IAM policy that grants Snowflake access to your S3 location. You can then attach the policy to a role, and use the security credentials generated by AWS for that role to access the files.