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.

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-id vpc-lattice \
  --principal vpc-lattice.amazonaws.com \
  --action lambda:InvokeFunction \
  --source-arn target-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 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:

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.

{
    "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"
    }
}

{
    "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

VPC Lattice supports requests from a client or responses from a Lambda function that contain headers with multiple values or contain the same header multiple times. VPC Lattice passes all values to the targets.

In the following example, there are two headers named header1 with different values.

header1 = value1
header1 = value2

With a V2 event structure, VPC Lattice sends the values in a list. For example:

"header1": ["value1", "value2"]

With a V1 event structure, VPC Lattice combines the values into a single string. For example:

"header1": "value1, value2"

Multi-value query string parameters

VPC Lattice supports query parameters with multiple values for the same key.

In the following example, there are two parameters named QS1 with different values.

http://www.example.com?&QS1=value1&QS1=value2

With a V2 event structure, VPC Lattice sends the values in a list. For example:

"QS1": ["value1", "value2"]

With a V1 event structure, VPC Lattice uses the last value passed. For example:

"QS1": "value2"

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 the Lambda function using the AWS CLI

Use the deregister-targets command.