AWS Lambda

  • v2 API reference

  • This filter should be configured with the name envoy.filters.http.aws_lambda.

Attention

The AWS Lambda filter is currently under active development.

The HTTP AWS Lambda filter is used to trigger an AWS Lambda function from a standard HTTP/1.x or HTTP/2 request. It supports a few options to control whether to pass through the HTTP request payload as is or to wrap it in a JSON schema.

If payload_passthrough is set to true, then the payload is sent to Lambda without any transformations. Note: This means you lose access to all the HTTP headers in the Lambda function.

However, if payload_passthrough is set to false, then the HTTP request is transformed to a JSON payload with the following schema:

  1. {
  2.     "rawPath": "/path/to/resource",
  3.     "method": "GET|POST|HEAD|...",
  4.     "headers": {"header-key": "header-value", ... },
  5.     "queryStringParameters": {"key": "value", ...},
  6.     "body": "...",
  7.     "isBase64Encoded": true|false
  8. }

  • rawPath is the HTTP request resource path (including the query string)

  • method is the HTTP request method. For example GET, PUT, etc.

  • headers are the HTTP request headers. If multiple headers share the same name, their values are coalesced into a single comma-separated value.

  • queryStringParameters are the HTTP request query string parameters. If multiple parameters share the same name, the last one wins. That is, parameters are _not_ coalesced into a single value if they share the same key name.

  • body the body of the HTTP request is base64-encoded by the filter if the content-type header exists and is _not_ one of the following:

    • text/*

    • application/json

    • application/xml

    • application/javascript

Otherwise, the body of HTTP request is added to the JSON payload as is.

On the other end, the response of the Lambda function must conform to the following schema:

  1. {
  2.     "statusCode": ...
  3.     "headers": {"header-key": "header-value", ... },
  4.     "cookies": ["key1=value1; HttpOnly; ...", "key2=value2; Secure; ...", ...],
  5.     "body": "...",
  6.     "isBase64Encoded": true|false
  7. }

  • The statusCode field is an integer used as the HTTP response code. If this key is missing, Envoy returns a 200 OK.

  • The headers are used as the HTTP response headers.

  • The cookies are used as Set-Cookie response headers. Unlike the request headers, cookies are _not_ part of the response headers because the Set-Cookie header cannot contain more than one value per the RFC. Therefore, Each key/value pair in this JSON array will translate to a single Set-Cookie header.

  • The body is base64-decoded if it is marked as base64-encoded and sent as the body of the HTTP response.

Note

The target cluster must have its endpoint set to the regional Lambda endpoint. Use the same region as the Lambda function.

AWS IAM credentials must be defined in either environment variables, EC2 metadata or ECS task metadata.

The filter supports per-filter configuration.

If you use the per-filter configuration, the target cluster _must_ have the following metadata:

  1. metadata:
  2.   filter_metadata:
  3.     com.amazonaws.lambda:
  4.       egress_gateway: true

Below are some examples that show how the filter can be used in different deployment scenarios.

Example configuration

In this configuration, the filter applies to all routes in the filter chain of the http connection manager:

  1. http_filters:
  2. - name: envoy.filters.http.aws_lambda
  3.   typed_config:
  4.     "@type": type.googleapis.com/envoy.extensions.filters.http.aws_lambda.v3.Config
  5.     arn: "arn:aws:lambda:us-west-2:987654321:function:hello_envoy"
  6.     payload_passthrough: true

The corresponding regional endpoint must be specified in the target cluster. So, for example if the Lambda function is in us-west-2:

  1. clusters:
  2. - name: lambda_egress_gateway
  3.   connect_timeout: 0.25s
  4.   type: LOGICAL_DNS
  5.   dns_lookup_family: V4_ONLY
  6.   lb_policy: ROUND_ROBIN
  7.   load_assignment:
  8.     cluster_name: lambda_egress_gateway
  9.     endpoints:
  10.     - lb_endpoints:
  11.       - endpoint:
  12.           address:
  13.             socket_address:
  14.               address: lambda.us-west-2.amazonaws.com
  15.               port_value: 443
  16.   transport_socket:
  17.     name: envoy.transport_sockets.tls
  18.     typed_config:
  19.       "@type": type.googleapis.com/envoy.api.v2.auth.UpstreamTlsContext
  20.       sni: "*.amazonaws.com"

The filter can also be configured per virtual-host, route or weighted-cluster. In that case, the target cluster must have specific Lambda metadata.

  1. weighted_clusters:
  2. clusters:
  3. - name: lambda_egress_gateway
  4.   weight: 42
  5.   typed_per_filter_config:
  6.     envoy.filters.http.aws_lambda:
  7.       "@type": type.googleapis.com/envoy.extensions.filters.http.aws_lambda.v3.PerRouteConfig
  8.       invoke_config:
  9.         arn: "arn:aws:lambda:us-west-2:987654321:function:hello_envoy"
  10.         payload_passthrough: false

An example with the Lambda metadata applied to a weighted-cluster:

  1. clusters:
  2. - name: lambda_egress_gateway
  3.   connect_timeout: 0.25s
  4.   type: LOGICAL_DNS
  5.   dns_lookup_family: V4_ONLY
  6.   lb_policy: ROUND_ROBIN
  7.   metadata:
  8.     filter_metadata:
  9.       com.amazonaws.lambda:
  10.         egress_gateway: true
  11.   load_assignment:
  12.     cluster_name: lambda_egress_gateway # does this have to match? seems redundant
  13.     endpoints:
  14.     - lb_endpoints:
  15.       - endpoint:
  16.           address:
  17.             socket_address:
  18.               address: lambda.us-west-2.amazonaws.com
  19.               port_value: 443
  20.   transport_socket:
  21.     name: envoy.transport_sockets.tls
  22.     typed_config:
  23.       "@type": type.googleapis.com/envoy.api.v2.auth.UpstreamTlsContext
  24.       sni: "*.amazonaws.com"