Lambda functions as targets in VPC Lattice
You can register your Lambda functions as targets with a VPC Lattice target group, and configure a listener rule to forward requests to the target group for your Lambda function. When the service forwards the request to a target group with a Lambda function as a target, it invokes your Lambda function and passes the content of the request to the Lambda function, in JSON format. For more information, see Using AWS Lambda with Amazon VPC Lattice in the AWS Lambda Developer Guide.
Limitations
-
The Lambda function and target group must be in the same account and in the same Region.
-
The maximum size of the request body that you can send to a Lambda function is 6 MB.
-
The maximum size of the response JSON that the Lambda function can send is 6 MB.
-
The protocol must be HTTP or HTTPS.
Prepare the Lambda function
The following recommendations apply if you are using your Lambda function with a VPC Lattice service.
Permissions to invoke the Lambda function
When you create the target group and register the Lambda function using the AWS Management Console or the AWS CLI, VPC Lattice adds the required permissions to your Lambda function policy on your behalf.
You can also add permissions on your own using the following API call:
aws lambda add-permission \ --function-name
lambda-function-arn-with-alias-name
\ --statement-idvpc-lattice
\ --principal vpc-lattice.amazonaws.com \ --action lambda:InvokeFunction \ --source-arntarget-group-arn
Lambda function versioning
You can register one Lambda function per target group. To ensure that you can change your Lambda function and that the VPC Lattice service always invokes the current version of the Lambda function, create a function alias and include the alias in the function ARN when you register the Lambda function with the VPC Lattice service. For more information, see Lambda function versions and Create an alias for a Lambda function in the AWS Lambda Developer Guide.
Create a target group for the Lambda function
Create a target group, which is used in request routing. If the request content matches a listener rule with an action to forward it to this target group, the VPC Lattice service invokes the registered Lambda function.
To create a target group and register the Lambda function using the console
Open the Amazon VPC console at https://console.aws.amazon.com/vpc/
. -
On the navigation pane, under VPC Lattice, choose Target groups.
-
Choose Create target group.
-
For Choose a target type, select Lambda function.
-
For Target group name, enter a name for the target group.
-
For Lambda event structure version, choose a version. For more information, see Receive events from the VPC Lattice service.
-
(Optional) To add tags, expand Tags, choose Add new tag, and enter the tag key and tag value.
-
Choose Next.
-
For Lambda function, do one of the following:
-
Select an existing Lambda function.
-
Create a new Lambda function and select it.
-
Register the Lambda function later.
-
-
Choose Create target group.
To create a target group and register the Lambda function using the AWS CLI
Use the create-target-group and register-targets commands.
Receive events from the VPC Lattice service
The VPC Lattice service supports Lambda invocation for requests over both HTTP and
HTTPS. The service sends an event in JSON format, and adds the
X-Forwarded-For
header to every request.
Base64 encoding
The service Base64 encodes the body if the content-encoding
header
is present and the content type is not one of the following:
-
text/*
-
application/json
-
application/xml
-
application/javascript
If the content-encoding
header is not present, Base64 encoding
depends on the content type. For the content types above, the service sends the
body as is, without Base64 encoding.
Event structure format
When you create or update a target group of type LAMBDA
, you can
specify the version of the event structure that your Lambda function receives.
The possible versions are V1
and V2
.
Example event: V2
{
"version": "2.0",
"path": "/",
"method": "GET|POST|HEAD|...",
"headers": {
"header-key
": ["header-value
", ...],
...
},
"queryStringParameters": {
"key
": ["value
", ...]
},
"body": "request-body
",
"isBase64Encoded": true|false,
"requestContext": {
"serviceNetworkArn": "arn:aws:vpc-lattice:region
:123456789012
:servicenetwork/sn-0bf3f2882e9cc805a
",
"serviceArn": "arn:aws:vpc-lattice:region
:123456789012
:service/svc-0a40eebed65f8d69c
",
"targetGroupArn": "arn:aws:vpc-lattice:region
:123456789012
:targetgroup/tg-6d0ecf831eec9f09
",
"identity": {
"sourceVpcArn": "arn:aws:ec2:region
:123456789012
:vpc/vpc-0b8276c84697e7339
",
"type": "AWS_IAM",
"principal": "arn:aws:iam::123456789012
:assumed-role/my-role
/my-session
",
"principalOrgID": "o-50dc6c495c0c9188
",
"sessionName": "i-0c7de02a688bde9f7
",
"x509IssuerOu": "string
",
"x509SanDns": "string
",
"x509SanNameCn": "string
",
"x509SanUri": "string
",
"x509SubjectCn": "string
"
},
"region": "region
",
"timeEpoch": "1690497599177430
"
}
}
body
The body of the request. Present only if the protocol is HTTP, HTTPS, or gRPC.
headers
The HTTP headers of the request. Present only if the protocol is HTTP, HTTPS, or gRPC.
identity
-
The identity information. The following are possible fields.
principal
– The authenticated principal. Present only if AWS authentication is successful.principalOrgID
– The ID of the organization for the authenticated principal. Present only if AWS authentication is successful.sessionName
– The name of the authenticated session. Present only if AWS authentication is successful.sourceVpcArn
– The ARN of the VPC where the request originated. Present only if the source VPC can be identified.type
– The value isAWS_IAM
if an auth policy is used and AWS authentication is successful.
If Roles Anywhere credentials are used and authentication is successful, the following are possible fields.
x509IssuerOu
– The issuer (OU).x509SanDns
– The subject alternative name (DNS).x509SanNameCn
– The issuer alternative name (Name/CN).x509SanUri
– The subject alternative name (URI).x509SubjectCn
– The subject name (CN).
isBase64Encoded
Indicates whether the body was base64 encoded. Present only if the protocol is HTTP, HTTPS, or gRPC and the request body is not already a string.
method
The HTTP method of the request. Present only if the protocol is HTTP, HTTPS, or gRPC.
path
The path of the request. Present only if the protocol is HTTP, HTTPS, or gRPC.
queryStringParameters
The HTTP query string parameters. Present only if the protocol is HTTP, HTTPS, or gRPC.
serviceArn
The ARN of the service that receives the request.
serviceNetworkArn
The ARN of the service network that delivers the request.
targetGroupArn
The ARN of the target group that receives the request.
timeEpoch
The time, in microseconds.
Example event: V1
{
"raw_path": "/path/to/resource
",
"method": "GET|POST|HEAD|...",
"headers": {"header-key
": "header-value
", ... },
"query_string_parameters": {"key
": "value
", ...},
"body": "request-body
",
"is_base64_encoded": true|false
}
Respond to the VPC Lattice service
The response from your Lambda function must include the Base64 encoding status, status code, and headers. You can omit the body.
To include a binary content in the body of the response, you must Base64 encode
the content and set isBase64Encoded
to true
. The service
decodes the content to retrieve the binary content and sends it to the client in the
body of the HTTP response.
The VPC Lattice service does not honor hop-by-hop headers, such as
Connection
or Transfer-Encoding
. You can omit the
Content-Length
header because the service computes it before
sending responses to clients.
The following is an example response from a Lambda function:
{ "isBase64Encoded":
false
, "statusCode":200
, "statusDescription": "200 OK
", "headers": { "Set-cookie": "cookies
", "Content-Type": "application/json" }, "body": "Hello from Lambda (optional)" }
Multi-value headers
By default, VPC Lattice supports requests from a client or responses from a Lambda function containing headers with multiple values or containing the same header multiple times. VPC Lattice also supports query parameters with multiple values for the same key.
For request headers, if multiple parameters share the same name, VPC Lattice will
pass both values to the targets. The following is an example where header
1
is the name of two separate headers:
header1 = foo header1 = bar
Then VPC Lattice sends both values to the targets:
"header1": ["foo", "bar"]
For query strings, if multiple parameters share the same name, the last value
wins. This means that parameters are _not_ coalesced
into a single
value if they share the same key name.
The following is an example where foo
and bar
are the
values of the parameters with the same name, QS1
:
http://www.example.com?&QS1=foo&QS1=bar
Then VPC Lattice sends the last value to the targets:
"QS1": "bar"
Deregister the Lambda function
If you no longer need to send traffic to your Lambda function, you can deregister it. After you deregister a Lambda function, in-flight requests fail with HTTP 5XX errors.
To replace a Lambda function, we recommend that you create a new target group, register the new function with the new target group, and update the listener rules to use the new target group instead of the existing one.
To deregister a Lambda function using the console
Open the Amazon VPC console at https://console.aws.amazon.com/vpc/
. -
On the navigation pane, under VPC Lattice, choose Target groups.
-
Choose the name of the target group to open its details page.
-
On the Targets tab, choose Deregister.
-
When prompted for confirmation, enter
confirm
and then choose Deregister.
To deregister the Lambda function using the AWS CLI
Use the deregister-targets command.