Configure a catalog integration for Amazon API Gateway¶

Create a REST API in Amazon API Gateway¶

To connect Snowflake to your Iceberg REST catalog, you need a REST API resource (https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-rest-api.html) in Amazon API Gateway.

If you don’t already have a REST API resource in Amazon API Gateway for your Iceberg catalog, you can create a simple REST API by modifying and importing an Iceberg catalog OpenAPI definition file or manually adding endpoints.

1. In the AWS Management Console, search for and select API Gateway.

2. Select Create API.

3. Select Build under REST API. To create a private REST API, select Build under REST API Private.

4. Select one of the following options:

   • To create an API by manually adding endpoints, select New API.

   • To create an API using an OpenAPI definition file, select Import API, then upload the file or paste the definition in the code editor.

5. Enter an API name and optional Description.

   Note

   You don’t need to enter a VPC endpoint ID when you create a private REST API.

6. Select Create API.

For more information about creating and developing a REST API in API Gateway, see the Amazon API Gateway Developer Guide (https://docs.aws.amazon.com/apigateway/latest/developerguide/rest-api-develop.html).

Create an IAM policy and attach it to a role¶

In this step, you create an AWS IAM role that Snowflake can use to connect to API Gateway. You attach a policy to the role that grants permission to call your API.

1. In the AWS Management Console, search for and select IAM.

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

3. Select Create policy and then select JSON for the Policy editor.

4. Replace the empty policy with a policy that has permission to invoke your API methods. For example, the following general policy allows the invoke action for all API Gateway resources in an AWS account.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
           "Effect": "Allow",
           "Action": [
               "execute-api:Invoke"
           ],
           "Resource": "arn:aws:execute-api:*:<aws_account_id>:*"
       }
     ]
   }
   

   Copy

   Important

   As a best practice, use a policy that grants the minimum required privileges for your use case. For additional guidance and example policies, see Control access to an API with IAM permissions (https://docs.aws.amazon.com/apigateway/latest/developerguide/permissions.html).

5. Select Next.

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

7. Select Create policy.

8. From the left-hand navigation pane in the IAM dashboard, select Roles.

9. Select a role to attach the policy to. When you create a catalog integration, you specify this role. If you don’t have a role, create a new role.

10. On the role Summary page in the Permissions tab, select Add permissions » Attach policies.

11. Search for and check the box next to the policy that you created for API Gateway, then select Add permissions.

12. On the role Summary page, copy the role ARN. You specify this ARN when you create a catalog integration.

Attach an API Gateway resource policy (private APIs only)¶

If your REST API is private, you must attach an Amazon API Gateway resource policy to your API. The resource policy allows Snowflake to call your API from the Amazon Virtual Private Cloud (VPC) in which your Snowflake account is located.

1. In Snowflake, call the SYSTEM$GET_SNOWFLAKE_PLATFORM_INFO function to retrieve the IDs for the VPC in which your Snowflake account is located. From the function output, for each property identified with “purpose”: “generic”, record the corresponding VPC ID(s).

   SELECT SYSTEM$GET_SNOWFLAKE_PLATFORM_INFO();
   

   Copy

   Output:

   {
     "snowflake-vpc-id": ["vpc-c1c234a5"],
     "snowflake-egress-vpc-ids": [
       ...
       {
         "id": "vpc-c1c234a5",
         "expires": "2025-03-01T00:00:00",
         "purpose": "generic"
       },
       ...
     ]
   }
   

2. Follow the instructions in Attaching API Gateway resource policies (https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-resource-policies-create-attach.html#apigateway-resource-policies-create-attach-console) to attach a resource policy to your REST API.

   Paste and modify the following example policy.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Deny",
         "Principal": "*",
         "Action": "execute-api:Invoke",
         "Resource": "<api_gateway_arn>",
         "Condition": {
           "StringNotEquals": {
             "aws:sourceVpc": "<snowflake_vpc_id>"
           }
         }
       },
       {
         "Effect": "Allow",
         "Principal": {
           "AWS": "arn:aws:sts::123456789XXX:assumed-role/<my_api_permissions_role_name>/snowflake"
         },
         "Action": "execute-api:Invoke",
         "Resource": "<api_gateway_arn>/*/*/*",
         "Condition": {
           "StringEquals": {
             "aws:sourceVpc": "<snowflake_vpc_id>"
           }
         }
       }
     ]
   }
   

   Copy

The first statement in the policy denies all requests that don’t originate from the Snowflake VPC. The second statement allows the invoke action (for all methods) from requests originating from the Snowflake VPC that use the assumed-role session principal (https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-role-session).

To learn more about API Gateway resource policies, see:

• Controlling access to an API with API Gateway resource policies (https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-resource-policies.html)

• API Gateway resource policy examples (https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-resource-policies-examples.html)

Select IAM-based authorization for your API¶

Select IAM-based authorization for each method that you want to provide access to in your REST API. With IAM-based authorization, Snowflake can use the IAM role that you configured to make calls to the API.

1. In the Amazon API Gateway console, select your REST API.

2. For each method:

   1. Under Resources, select a method from the list.

   2. Under Method request settings, select Edit.

   3. For Authorization, select AWS IAM.

   4. Select Save.

3. To apply the authorization changes, select Deploy API. For more information, see Deploying a REST API from the API Gateway console (https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-deploy-api-with-console.html).

Retrieve the endpoint URL¶

Retrieve your REST API endpoint URL (or invoke URL). Your API must be deployed to a stage before you can retrieve the endpoint URL.

1. In the Amazon API Gateway console, select your REST API.

2. In the left-hand navigation pane, select Stages.

3. Under Stage details, copy the Invoke URL.

You specify the endpoint URL when you create a catalog integration.

Create a catalog integration for SigV4¶

After you have a REST API in Amazon API Gateway and have completed the initial steps to control access to your API using IAM permissions, you can create a catalog integration in Snowflake.

To view the command syntax and parameter descriptions, see CREATE CATALOG INTEGRATION (Apache Iceberg™ REST).

Public REST API

To create a catalog integration for a public REST API, specify ICEBERG_REST as the CATALOG_SOURCE and use SIGV4 authentication.

Include details such as your API endpoint URL and IAM role ARN.

CREATE OR REPLACE CATALOG INTEGRATION my_rest_catalog_integration
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'my_namespace'
  REST_CONFIG = (
    CATALOG_URI = 'https://asdlkfjwoalk-execute-api.us-west-2-amazonaws.com/MyApiStage'
    CATALOG_API_TYPE = AWS_API_GATEWAY
  )
  REST_AUTHENTICATION = (
    TYPE = SIGV4
    SIGV4_IAM_ROLE = 'arn:aws:iam::123456789XXX:role/my_api_permissions_role'
    SIGV4_EXTERNAL_ID = 'my_iceberg_external_id'
  )
  ENABLED = TRUE;

Private REST API

To create a catalog integration for a private REST API, you must set the CATALOG_API_TYPE parameter to AWS_PRIVATE_API_GATEWAY.

CREATE OR REPLACE CATALOG INTEGRATION my_rest_catalog_integration
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'my_namespace'
  REST_CONFIG = (
    CATALOG_URI = 'https://asdlkfjwoalk-execute-api.us-west-2-amazonaws.com/MyApiStage'
    CATALOG_API_TYPE = AWS_PRIVATE_API_GATEWAY
  )
  REST_AUTHENTICATION = (
    TYPE = SIGV4
    SIGV4_IAM_ROLE = 'arn:aws:iam::123456789XXX:role/my_api_permissions_role'
    SIGV4_EXTERNAL_ID = 'my_iceberg_external_id'
  )
  ENABLED = TRUE;

Configure the trust relationship in IAM¶

Retrieve information about the AWS IAM user that was created for your Snowflake account when you created the catalog integration, and configure the trust relationship for your IAM role.

1. In Snowflake, call the DESCRIBE CATALOG INTEGRATION command:

   DESCRIBE CATALOG INTEGRATION my_rest_catalog_integration;
   

   Copy

   Record the following values:

   Value	Description
   API_AWS_IAM_USER_ARN	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.
   API_AWS_EXTERNAL_ID	The external ID that’s needed to establish a trust relationship. If you didn’t specify an external ID (SIGV4_EXTERNAL_ID) when you created the catalog integration, 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.

2. In the AWS Management Console, search for and select IAM.

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

4. Select the IAM role that you created for your catalog integration.

5. Select the Trust relationships tab.

6. Select Edit trust policy.

7. Modify the policy document with the values that you recorded.

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

   Copy

8. Select Update policy to save your changes.