Skip to content

Commit 05e99d8

Browse files
julianwoodjulianwood
authored
Merge pull request #2897 from biswanathmukherjee/biswanathmukherjee-feature-apigw-vpclink-alb-ecs
Amazon API Gateway private integration with Application Load Balancer with VPC LinkV2
2 parents 6dabde9 + 78fb851 commit 05e99d8

File tree

10 files changed

+1327
-0
lines changed

10 files changed

+1327
-0
lines changed

‎apigw-vpclink-alb-ecs/.dockerignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
node_modules
2+
npm-debug.log
3+
.git
4+
.gitignore
5+
README.md
6+
.env
7+
.nyc_output
8+
coverage
9+
.kiro

‎apigw-vpclink-alb-ecs/Dockerfile‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Use official Node.js runtime as base image
2+
FROM node:24-alpine
3+
4+
# Set working directory in container
5+
WORKDIR /app
6+
7+
# Copy package files
8+
COPY package*.json ./
9+
10+
# Install dependencies
11+
RUN npm ci --only=production
12+
13+
# Copy application source code
14+
COPY src/ ./src/
15+
16+
# Expose port 3000
17+
EXPOSE 3000
18+
19+
# Create non-root user for security
20+
RUN addgroup -g 1001 -S nodejs
21+
RUN adduser -S nodejs -u 1001
22+
USER nodejs
23+
24+
# Start the application
25+
CMD ["npm", "start"]

‎apigw-vpclink-alb-ecs/README.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
# REST APIs using Amazon API Gateway private integration with Application Load Balancer
2+
3+
This sample project demonstrates how API Gateway connects to Application Load Balancer using VPV Link V2.
4+
5+
## Requirements
6+
7+
- [Create an AWS account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html) if you do not already have one and log in. The IAM user that you use must have sufficient permissions to make necessary AWS service calls and manage AWS resources.
8+
- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) installed and configured
9+
- [Git Installed](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
10+
- [AWS Serverless Application Model](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html) (AWS SAM) installed
11+
- [Node 24 or above](https://nodejs.org/en/download) installed
12+
- [Docker] installed
13+
14+
## Deployment Instructions
15+
16+
1. Create a new directory, navigate to that directory in a terminal and clone the GitHub repository:
17+
18+
```bash
19+
git clone https://github.com/aws-samples/serverless-patterns
20+
```
21+
22+
2. Change directory to the pattern directory:
23+
24+
```bash
25+
cd serverless-patterns/apigw-vpclink-alb-ecs
26+
```
27+
28+
3. Create an ECR repository:
29+
30+
```bash
31+
aws ecr create-repository --repository-name products-api --region <your-region>
32+
```
33+
34+
4. Get the login token and authenticate Docker:
35+
36+
```bash
37+
aws ecr get-login-password --region <your-region> | docker login --username AWS --password-stdin <account-id>.dkr.ecr.<your-region>.amazonaws.com
38+
```
39+
40+
5. Install dependencies:
41+
42+
```bash
43+
npm install
44+
```
45+
46+
6. Build the Docker image and push it to ECR:
47+
48+
```bash
49+
# Build the Docker image
50+
docker build --platform linux/amd64 -t products-api .
51+
52+
# Tag the image for ECR
53+
docker tag products-api:latest <account-id>.dkr.ecr.<your-region>.amazonaws.com/products-api:latest
54+
55+
# Push the image to ECR
56+
docker push <account-id>.dkr.ecr.<your-region>.amazonaws.com/products-api:latest
57+
```
58+
59+
7. From the command line, run the following commands:
60+
61+
```bash
62+
sam build
63+
sam deploy --guided
64+
```
65+
66+
8. During the prompts:
67+
68+
- Enter a stack name
69+
- Enter the desired AWS Region e.g. `us-east-1`.
70+
- Enter VpcCidr - keep the default value
71+
- Enter ECRImageURI - Replace with your ECR URI from the previous step. e.g. <account-id>.dkr.ecr.<your-region>.amazonaws.com/products-api:latest
72+
- Allow SAM CLI to create IAM roles with the required permissions.
73+
- Keep default values to the rest of the parameters.
74+
75+
Once you have run `sam deploy --guided` mode once and saved arguments to a configuration file (samconfig.toml), you can use `sam deploy` in future to use these defaults.
76+
77+
9. Note the outputs from the SAM deployment process. These contain the resource names and/or ARNs which are used for next step as well as testing.
78+
79+
## How it works
80+
81+
The SAM template deploys the following resources:
82+
83+
![End to End Architecture](diagram/architecture.png)
84+
85+
Here's a breakdown of the steps:
86+
87+
1. **Amazon API Gateway**: The API Gateway exposes a REST API endpoint. The API Gateway connects to Application Load Balancer using VPC link V2.
88+
89+
## Testing
90+
91+
### Using EC2 Instance test internal ALB
92+
93+
1. Open a terminal in your laptop and use [curl](https://curl.se/) to send a HTTP GET request to the `InternalALBEndpoint`. Replace the value of `InternalALBEndpoint` from `sam deploy` output.
94+
95+
```bash
96+
curl -X GET <InternalALBEndpoint>
97+
```
98+
99+
Expected Response:
100+
This request will timeout and you will not get any response. This is an internal ALB endpoint. Hence, this is not accessible over public internet.
101+
102+
2. [Launch an EC2 instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html#ec2-launch-instance) in one of the private subnets within the same VPC. Refer the `sam deploy` output for the VPC, subnet and security group details.
103+
104+
3. [Connect to your EC2 instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html#ec2-connect-to-instance)
105+
106+
4. Install curl if not available:
107+
108+
```bash
109+
# Amazon Linux/RHEL/CentOS
110+
sudo yum install -y curl
111+
112+
# Ubuntu/Debian
113+
sudo apt-get update && sudo apt-get install -y curl
114+
```
115+
116+
5. Test the products endpoint functionality
117+
118+
```bash
119+
curl -X GET <InternalALBEndpoint>
120+
```
121+
122+
Expected Response:
123+
124+
```json
125+
{
126+
"products": [
127+
{
128+
"id": "1",
129+
"name": "Sample Product",
130+
"description": "A demo product for testing",
131+
"price": 29.99,
132+
"category": "Electronics"
133+
},
134+
{
135+
"id": "2",
136+
"name": "Demo Widget",
137+
"description": "Another test product",
138+
"price": 15.50,
139+
"category": "Gadgets"
140+
},
141+
{
142+
"id": "3",
143+
"name": "Test Item",
144+
"description": "Third demo product",
145+
"price": 99.99,
146+
"category": "Tools"
147+
}
148+
]
149+
}
150+
```
151+
152+
6. Now, test the API Gateway API endpoint. Replace `APIEndpoint` with the value from `sam deploy` output.
153+
154+
```bash
155+
curl -X GET <APIEndpoint>
156+
```
157+
158+
Expected Response:
159+
160+
```json
161+
{
162+
"products": [
163+
{
164+
"id": "1",
165+
"name": "Sample Product",
166+
"description": "A demo product for testing",
167+
"price": 29.99,
168+
"category": "Electronics"
169+
},
170+
{
171+
"id": "2",
172+
"name": "Demo Widget",
173+
"description": "Another test product",
174+
"price": 15.50,
175+
"category": "Gadgets"
176+
},
177+
{
178+
"id": "3",
179+
"name": "Test Item",
180+
"description": "Third demo product",
181+
"price": 99.99,
182+
"category": "Tools"
183+
}
184+
]
185+
}
186+
```
187+
188+
## Cleanup
189+
190+
1. Delete the EC2 instance created for testing.
191+
192+
2. To delete the resources deployed to your AWS account via AWS SAM, run the following command:
193+
194+
```bash
195+
sam delete
196+
```
197+
198+
3. Delete the ECR repository. Ensure that you are deleting the correct repository.
199+
200+
201+
```bash
202+
aws ecr delete-repository --repository-name products-api --region <your-region> --force
203+
```
204+
205+
---
206+
207+
Copyright 2026 Amazon.com, Inc. or its affiliates. All Rights Reserved.
208+
209+
SPDX-License-Identifier: MIT-0

‎apigw-vpclink-alb-ecs/apigw-vpclink-alb-ecs.json‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
{
2+
"title": "Amazon API Gateway private integration with Application Load Balancer",
3+
"description": "This sample project demonstrates how API Gateway connects to Application Load Balancer using VPV Link V2.",
4+
"language": "Node.js",
5+
"level": "200",
6+
"framework": "AWS SAM",
7+
"introBox": {
8+
"headline": "How it works",
9+
"text": [
10+
"Amazon API Gateway receives the HTTP GET request.",
11+
"The API Gateway routes the request to Application Load Balancer using VPC link V2.",
12+
"The Application Load Balancer routes the request to one of the tasks under Amazon ECS cluster."
13+
]
14+
},
15+
"gitHub": {
16+
"template": {
17+
"repoURL": "https://github.com/aws-samples/serverless-patterns/tree/main/apigw-vpclink-alb-ecs",
18+
"templateURL": "serverless-patterns/apigw-vpclink-alb-ecs",
19+
"projectFolder": "apigw-vpclink-alb-ecs",
20+
"templateFile": "template.yaml"
21+
}
22+
},
23+
"resources": {
24+
"bullets": [
25+
{
26+
"text": "AWS Lambda tenant isolation",
27+
"link": "https://docs.aws.amazon.com/lambda/latest/dg/tenant-isolation.html"
28+
},
29+
{
30+
"text": "AWS Blog - Build scalable REST APIs using Amazon API Gateway private integration with Application Load Balancer",
31+
"link": "https://aws.amazon.com/blogs/compute/build-scalable-rest-apis-using-amazon-api-gateway-private-integration-with-application-load-balancer/"
32+
}
33+
]
34+
},
35+
"deploy": {
36+
"text": ["sam build", "sam deploy --guided"]
37+
},
38+
"testing": {
39+
"text": ["See the GitHub repo for detailed testing instructions."]
40+
},
41+
"cleanup": {
42+
"text": ["Delete the stack: <code>sam delete</code>."]
43+
},
44+
"authors": [
45+
{
46+
"name": "Biswanath Mukherjee",
47+
"image": "https://serverlessland.com/assets/images/resources/contributors/biswanath-mukherjee.jpg",
48+
"bio": "I am a Sr. Solutions Architect working at AWS India. I help strategic global enterprise customer to architect their workload to run on AWS.",
49+
"linkedin": "biswanathmukherjee"
50+
}
51+
],
52+
"patternArch": {
53+
"icon1": {
54+
"x": 15,
55+
"y": 50,
56+
"service": "apigw",
57+
"label": "API Gateway"
58+
},
59+
"icon2": {
60+
"x": 40,
61+
"y": 50,
62+
"service": "vpc-endpoint",
63+
"label": "VPC Link V2"
64+
},
65+
"icon3": {
66+
"x": 65,
67+
"y": 50,
68+
"service": "alb",
69+
"label": "ALB"
70+
},
71+
"icon4": {
72+
"x": 90,
73+
"y": 50,
74+
"service": "ecs",
75+
"label": "Amazon ECS"
76+
},
77+
"line1": {
78+
"from": "icon1",
79+
"to": "icon2",
80+
"label": ""
81+
},
82+
"line2": {
83+
"from": "icon2",
84+
"to": "icon3",
85+
"label": ""
86+
},
87+
"line3": {
88+
"from": "icon3",
89+
"to": "icon4",
90+
"label": ""
91+
}
92+
}
93+
}

‎apigw-vpclink-alb-ecs/diagram/architecture.png‎

45.7 KB
Loading

0 commit comments

Comments
 (0)