AWS apigateway documentation change
Summary
Updated tutorial to use VPC link V2 with Amazon ECS service instead of Network Load Balancer, added detailed step-by-step instructions including CloudFormation template usage, testing, deployment, and cleanup procedures.
Security assessment
The changes focus on updating integration methods to newer VPC link V2 and ECS service patterns, but there's no evidence of addressing specific vulnerabilities. Security aspects mentioned (VPC configuration, security groups) are part of standard setup documentation rather than new security features or vulnerability mitigations.
Diff
diff --git a/apigateway/latest/developerguide/getting-started-with-private-integration.md b/apigateway/latest/developerguide/getting-started-with-private-integration.md index b49d66369..f5d89e114 100644 --- a//apigateway/latest/developerguide/getting-started-with-private-integration.md +++ b//apigateway/latest/developerguide/getting-started-with-private-integration.md @@ -4,0 +5,2 @@ +Step 1: Create an Amazon ECS serviceStep 2: Create a VPC linkStep 3: Create a REST APIStep 4: Test your APIStep 5: Deploy your APIStep 6: Call your APIStep 7: Clean up + @@ -7 +9 @@ -You can create an API Gateway API with private integration to provide your customers access to HTTP/HTTPS resources within your Amazon Virtual Private Cloud (Amazon VPC). Such VPC resources are HTTP/HTTPS endpoints on an EC2 instance behind a Network Load Balancer in the VPC. The Network Load Balancer encapsulates the VPC resource and routes incoming requests to the targeted resource. +In this tutorial, you create a REST API that connects to an Amazon ECS service that runs in an Amazon VPC. Clients outside of your Amazon VPC can use the API to access your Amazon ECS service. @@ -9 +11 @@ You can create an API Gateway API with private integration to provide your custo -When a client calls the API, API Gateway connects to the Network Load Balancer through the pre-configured VPC link. A VPC link is encapsulated by an API Gateway resource of [VpcLink](https://docs.aws.amazon.com/apigateway/latest/api/API_VpcLink.html). It is responsible for forwarding API method requests to the VPC resources and returns backend responses to the caller. For an API developer, a `VpcLink` is functionally equivalent to an integration endpoint. +This tutorial takes approximately an hour to complete. First, you use an CloudFormation template to create a Amazon VPC and Amazon ECS service. Then you use the API Gateway console to create a VPC link V2. The VPC link allows API Gateway to access the Amazon ECS service that runs in your Amazon VPC. Next, you create a REST API that uses the VPC link V2 to connect to your Amazon ECS service. Lastly, you test your API. @@ -11 +13 @@ When a client calls the API, API Gateway connects to the Network Load Balancer t -To create an API with private integration, you must create a new `VpcLink`, or choose an existing one, that is connected to a Network Load Balancer that targets the desired VPC resources. You must have [appropriate permissions](./grant-permissions-to-create-vpclink.html) to create and manage a `VpcLink`. You then set up an API [method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) and integrate it with the `VpcLink` by setting either `HTTP` or `HTTP_PROXY` as the [integration type](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type), setting `VPC_LINK` as the integration [connection type](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#connectionType), and setting the `VpcLink` identifier on the integration [`connectionId`](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#connectionId). +When you invoke your REST API, API Gateway routes the request to your Amazon ECS service through your VPC link V2, and then returns the response from the service. @@ -15 +17,42 @@ To create an API with private integration, you must create a new `VpcLink`, or c -The Network Load Balancer and API must be owned by the same AWS account. +This tutorial was previously supported for HTTP APIs, and now is supported for REST APIs using VPC link V2. + + + +To complete this tutorial, you need an AWS account and an AWS Identity and Access Management user with console access. For more information, see [Set up to use API Gateway](./setting-up.html). + +###### Topics + + * Step 1: Create an Amazon ECS service + + * Step 2: Create a VPC link + + * Step 3: Create a REST API + + * Step 4: Test your API + + * Step 5: Deploy your API + + * Step 6: Call your API + + * Step 7: Clean up + + + + +## Step 1: Create an Amazon ECS service + +Amazon ECS is a container management service that makes it easy to run, stop, and manage Docker containers on a cluster. In this tutorial, you run your cluster on a serverless infrastructure that's managed by Amazon ECS. + +Download and unzip [this CloudFormation template](samples/rest-private-integration-tutorial.zip), which creates all of the dependencies for the service, including an Amazon VPC. You use the template to create an Amazon ECS service that uses an Application Load Balancer. + +###### To create an CloudFormation stack + + 1. Open the CloudFormation console at [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). + + 2. Choose **Create stack** and then choose **With new resources (standard)**. + + 3. For **Specify template** , choose **Upload a template file**. + + 4. Select the template that you downloaded. + + 5. Choose **Next**. @@ -17 +60 @@ The Network Load Balancer and API must be owned by the same AWS account. -To quickly get started creating an API to access VPC resources, we walk through the essential steps for building an API with the private integration, using the API Gateway console. Before creating the API, do the following: + 6. For **Stack name** , enter `rest-api-private-integrations-tutorial` and then choose **Next**. @@ -19 +62 @@ To quickly get started creating an API to access VPC resources, we walk through - 1. Create a VPC resource, create or choose a Network Load Balancer under your account in the same region, and add the EC2 instance hosting the resource as a target of the Network Load Balancer. For more information, see [Set up a Network Load Balancer for API Gateway private integrations](./set-up-nlb-for-vpclink-using-console.html). + 7. For **Configure stack options** , choose **Next**. @@ -21 +64 @@ To quickly get started creating an API to access VPC resources, we walk through - 2. Grant permissions to create the VPC links for private integrations. For more information, see [Grant permissions for API Gateway to create a VPC link](./grant-permissions-to-create-vpclink.html). + 8. For **Capabilities** , acknowledge that CloudFormation can create IAM resources in your account. @@ -22,0 +66 @@ To quickly get started creating an API to access VPC resources, we walk through + 9. Choose **Next** , and then choose **Submit**. @@ -26 +69,0 @@ To quickly get started creating an API to access VPC resources, we walk through -After creating your VPC resource and your Network Load Balancer with your VPC resource configured in its target groups, follow the instructions below to create an API and integrate it with the VPC resource via a `VpcLink` in a private integration. @@ -28 +71,36 @@ After creating your VPC resource and your Network Load Balancer with your VPC re -###### To create an API with a private integration +CloudFormation provisions the ECS service, which can take a few minutes. When the status of your CloudFormation stack is **CREATE_COMPLETE** , you're ready to move on to the next step. + +## Step 2: Create a VPC link + +A VPC link allows API Gateway to access private resources in an Amazon VPC. You use a VPC link to allow clients to access your Amazon ECS service through your REST API. + +###### To create a VPC link + + 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). + + 2. On the main navigation pane, choose **VPC links** and then choose **Create**. + +You might need to choose the menu icon to open the main navigation pane. + + 3. For **Choose a VPC link version** , select **VPC link V2**. + + 4. For **Name** , enter `private-integrations-tutorial`. + + 5. For **VPC** , choose the VPC that you created in step 1. The name should start with **RestApiStack**. + + 6. For **Subnets** , select the two private subnets in your VPC. Their names end with `PrivateSubnet`. + + 7. For **Security groups** , select the Group ID that starts with `private-integrations-tutorial` and has the description of `RestApiStack/RestApiTutorialService/Service/SecurityGroup`. + + 8. Choose **Create**. + + + + +After you create your VPC link V2, API Gateway provisions Elastic Network Interfaces to access your VPC. The process can take a few minutes. In the meantime, you can create your API. + +## Step 3: Create a REST API + +The REST API provides an HTTP endpoint for your Amazon ECS service. + +###### To create a REST API @@ -32 +110 @@ After creating your VPC resource and your Network Load Balancer with your VPC re - 2. If this is your first time using API Gateway, you see a page that introduces you to the features of the service. Under **REST API** , choose **Build**. When the **Create Example API** popup appears, choose **OK**. + 2. Choose **Create API** , and then for **REST API** , choose **Build**. @@ -34 +112 @@ After creating your VPC resource and your Network Load Balancer with your VPC re -If this is not your first time using API Gateway, choose **Create API**. Under **REST API** , choose **Build**. + 3. For **Name** , enter `private-integration-api`. @@ -36 +114 @@ If this is not your first time using API Gateway, choose **Create API**. Under * - 3. Create an edge-optimized or Regional REST API. For **IP address type** , use **IPv4**. + 4. For **IP address type** , select **IPv4**. @@ -38 +116 @@ If this is not your first time using API Gateway, choose **Create API**. Under * - 4. Select your API. + 5. Choose **Create API**. @@ -40 +118,3 @@ If this is not your first time using API Gateway, choose **Create API**. Under * - 5. Choose **Create method** , and then do the following: +After you create your API, you create a method. + + 6. Choose **Create method** , and then do the following: @@ -50 +130,3 @@ If this is not your first time using API Gateway, choose **Create API**. Under * - 5. For **VPC link** , select **[Use stage variable]** and enter `${stageVariables.vpcLinkId}` in the text box below. + 5. For **VPC link** , choose the VPC link V2 you created in the previous step. + + 6. For **Integration target** , enter the load balancer that you created with the CloudFormation template in Step 1. It's name should start with **rest-**. @@ -52 +134 @@ If this is not your first time using API Gateway, choose **Create API**. Under * -You define the `vpcLinkId` stage variable after deploying the API to a stage and set its value to the ID of the `VpcLink`. + 7. For **Endpoint URL** , enter `http://private-integrations-tutorial.com`. @@ -54 +136 @@ You define the `vpcLinkId` stage variable after deploying the API to a stage and - 6. For **Endpoint URL** , enter a URL, for example, `http://myApi.example.com`. +The URL is used to set the `Host` header of the integration request. In this case, the host header is `private-integrations-tutorial`. @@ -56 +138 @@ You define the `vpcLinkId` stage variable after deploying the API to a stage and -The URL must be a valid top-level domain and the host name (for example, `myApi.example.com`) is used to set the `Host` header of the integration request. + 8. Choose **Create method**. @@ -58 +140 @@ The URL must be a valid top-level domain and the host name (for example, `myApi. - 7. Choose **Create method**. +With the proxy integration, the API is ready to test. @@ -60 +141,0 @@ The URL must be a valid top-level domain and the host name (for example, `myApi. -With the proxy integration, the API is ready for deployment. Otherwise, you need to proceed to set up appropriate method responses and integration responses. @@ -62 +142,0 @@ With the proxy integration, the API is ready for deployment. Otherwise, you need - 6. Choose **Deploy API** , and then do the following: @@ -64 +143,0 @@ With the proxy integration, the API is ready for deployment. Otherwise, you need - 1. For **Stage** , select **New stage**. @@ -66 +145,73 @@ With the proxy integration, the API is ready for deployment. Otherwise, you need - 2. For **Stage name** , enter a stage name. +## Step 4: Test your API + +Next, you test invoking the API method. + +###### To test your API + + 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). + + 2. Choose your API. + + 3. Choose the **Test** tab. You might need to choose the right arrow button to show the tab. + + 4. Choose **Test** + +Verify that your API's response is a welcome message that tells you that your app is running on Amazon ECS. + + + + +## Step 5: Deploy your API + +Next, you deploy your API. + +###### To deploy your API + + 1. Choose **Deploy API**. + + 2. For **Stage** , select **New stage**. + + 3. For **Stage name** , enter `Prod`. + + 4. (Optional) For **Description** , enter a description. + + 5. Choose **Deploy**. + + + + +## Step 6: Call your API + +After your API is deployed, you can call it. + +###### To call your API + + 1. Enter the invoke URL in a web browser. + +The full URL should look like `https://`abcd123`.execute-api.`us-east-2`.amazonaws.com/Prod`.