AWS Lambda plugin | Kong Docs

Invoke an AWS Lambda function from Kong. It can be used in combination with other request plugins to secure, manage, or extend the function.

Note: The functionality of this plugin as bundled with versions of Kong prior to 0.14.0 and Kong Enterprise prior to 0.34 differs from what is documented herein. Refer to the CHANGELOG for details.

Configuration Reference

This plugin is compatible with requests with the following protocols:

http
https

This plugin is compatible with DB-less mode.

In DB-less mode, you configure Kong Gateway declaratively. Therefore, the Admin API is mostly read-only. The only tasks it can perform are all related to handling the declarative config, including:

setting a target's health status in the load balancer
validating configurations against schemas
uploading the declarative configuration using the /config endpoint

Enable the plugin on a service

Admin API

Kubernetes

Declarative (YAML)

Konnect Cloud

Manager

For example, configure this plugin on a service by making the following request:

curl -X POST http://{HOST}:8001/services/{SERVICE}/plugins \
    --data "name=aws-lambda"  \
    --data-urlencode "config.aws_key=AWS_KEY" \
    --data-urlencode "config.aws_secret=AWS_SECRET" \
    --data "config.aws_region=AWS_REGION" \
    --data "config.function_name=LAMBDA_FUNCTION_NAME" \
    --data "config.timeout=60000" \
    --data "config.keepalive=60000"

SERVICE is the id or name of the service that this plugin configuration will target.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <aws-lambda-example>
config: 
  aws_key: AWS_KEY
  aws_secret: AWS_SECRET
  aws_region: AWS_REGION
  function_name: LAMBDA_FUNCTION_NAME
  timeout: 60000
  keepalive: 60000
plugin: aws-lambda

Next, apply the KongPlugin resource to a Service by annotating the Service as follows:

apiVersion: v1
kind: Service
metadata:
  name: {SERVICE}
  labels:
    app: {SERVICE}
  annotations:
    konghq.com/plugins: <aws-lambda-example>
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
    name: {SERVICE}
  selector:
    app: {SERVICE}

{SERVICE} is the id or name of the service that this plugin configuration will target.

Note: The KongPlugin resource only needs to be defined once and can be applied to any service, consumer, or route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

For example, configure this plugin on a service by adding this section to your declarative configuration file:

plugins:
- name: aws-lambda
  service: {SERVICE}
  config: 
    aws_key: AWS_KEY
    aws_secret: AWS_SECRET
    aws_region: AWS_REGION
    function_name: LAMBDA_FUNCTION_NAME
    timeout: 60000
    keepalive: 60000

SERVICE is the id or name of the service that this plugin configuration will target.

Configure this plugin on a service:

In Konnect Cloud, select the service on the ServiceHub page.
Scroll down to Versions and select the version.
Scroll down to Plugins and click New Plugin.
Find and select the AWS Lambda plugin.
Enter the following parameters, updating the default or sample values as needed:
- Config.Function Name: LAMBDA_FUNCTION_NAME
- Config.Timeout: 60000
- Config.Keepalive: 60000
Click Create.

Configure this plugin on a service:

In Kong Manager, select the workspace.
From the Dashboard, scroll down to Services and click View for the service row.
Scroll down to plugins and click Add Plugin.
Find and select the AWS Lambda plugin.

Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
If the option is available, select Scoped.
Add the service name and ID to the Service field if it is not already prefilled.
Enter the following parameters, updating the default or sample values as needed:
- Config.Function Name: LAMBDA_FUNCTION_NAME
- Config.Timeout: 60000
- Config.Keepalive: 60000
Click Create.

Enable the plugin on a route

Admin API

Kubernetes

Declarative (YAML)

Konnect Cloud

Manager

For example, configure this plugin on a route with:

$ curl -X POST http://{HOST}:8001/routes/{ROUTE}/plugins \
    --data "name=aws-lambda"  \
    --data-urlencode "config.aws_key=AWS_KEY" \
    --data-urlencode "config.aws_secret=AWS_SECRET" \
    --data "config.aws_region=AWS_REGION" \
    --data "config.function_name=LAMBDA_FUNCTION_NAME" \
    --data "config.timeout=60000" \
    --data "config.keepalive=60000"

ROUTE is the id or name of the route that this plugin configuration will target.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <aws-lambda-example>
config: 
  aws_key: AWS_KEY
  aws_secret: AWS_SECRET
  aws_region: AWS_REGION
  function_name: LAMBDA_FUNCTION_NAME
  timeout: 60000
  keepalive: 60000
plugin: aws-lambda

Then, apply it to an ingress (Route or Routes) by annotating the ingress as follows:

apiVersion: networking/v1beta1
kind: Ingress
metadata:
  name: {ROUTE}
  annotations:
    kubernetes.io/ingress.class: kong
    konghq.com/plugins: <aws-lambda-example>
spec:
  rules:
  - host: examplehostname.com
    http:
      paths:
      - path: /bar
        backend:
          serviceName: echo
          servicePort: 80

ROUTE is the id or name of the route that this plugin configuration will target.

For example, configure this plugin on a route by adding this section to your declarative configuration file:

plugins:
- name: aws-lambda
  route: <route>
  config: 
    aws_key: AWS_KEY
    aws_secret: AWS_SECRET
    aws_region: AWS_REGION
    function_name: LAMBDA_FUNCTION_NAME
    timeout: 60000
    keepalive: 60000

ROUTE is the id or name of the route that this plugin configuration will target.

Configure this plugin on a route:

In Konnect Cloud, select the service from the ServiceHub page.
Scroll down to Versions and select the version.
Select the route.
Scroll down to Plugins and click Add Plugin.
Find and select the AWS Lambda plugin.
Enter the following parameters, updating the default or sample values as needed:
- Config.Function Name: LAMBDA_FUNCTION_NAME
- Config.Timeout: 60000
- Config.Keepalive: 60000
Click Create.

Configure this plugin on a route:

In Kong Manager, select the workspace.
From the Dashboard, select Routes in the left navigation.
Click View for the route row.
Scroll down to plugins and click Add Plugin.
Find and select the AWS Lambda plugin.

Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
If the option is available, select Scoped.
Add the Route ID if it is not already prefilled.
Enter the following parameters, updating the default or sample values as needed:
- Config.Function Name: LAMBDA_FUNCTION_NAME
- Config.Timeout: 60000
- Config.Keepalive: 60000
Click Create.

Enabling the plugin on a consumer

Admin API

Kubernetes

Declarative (YAML)

Manager

For example, configure this plugin on a consumer with:

$ curl -X POST http://{HOST}:8001/consumers/{CONSUMER}/plugins \
    --data "name=aws-lambda"  \
    --data-urlencode "config.aws_key=AWS_KEY" \
    --data-urlencode "config.aws_secret=AWS_SECRET" \
    --data "config.aws_region=AWS_REGION" \
    --data "config.function_name=LAMBDA_FUNCTION_NAME" \
    --data "config.timeout=60000" \
    --data "config.keepalive=60000"

CONSUMER is the id or username of the consumer that this plugin configuration will target.

You can combine consumer.id, service.id, or route.id in the same request, to further narrow the scope of the plugin.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <aws-lambda-example>
config: 
  aws_key: AWS_KEY
  aws_secret: AWS_SECRET
  aws_region: AWS_REGION
  function_name: LAMBDA_FUNCTION_NAME
  timeout: 60000
  keepalive: 60000
plugin: aws-lambda

Then, apply it to a consumer by annotating the KongConsumer resource as follows:

apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
  name: {CONSUMER}
  annotations:
    konghq.com/plugins: <aws-lambda-example>
    kubernetes.io/ingress.class: kong

CONSUMER is the id or username of the consumer that this plugin configuration will target.

Note: The KongPlugin resource only needs to be defined once and can be applied to any Service, Consumer, or Route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

For example, configure this plugin on a consumer by adding this section to your declarative configuration file:

plugins:
- name: aws-lambda
  consumer: {CONSUMER}
  config: 
    aws_key: AWS_KEY
    aws_secret: AWS_SECRET
    aws_region: AWS_REGION
    function_name: LAMBDA_FUNCTION_NAME
    timeout: 60000
    keepalive: 60000

CONSUMER is the id or username of the consumer that this plugin configuration will target.

Configure this plugin on a consumer:

In Kong Manager, select the workspace.
From the Dashboard, scroll down to Consumers and click View for the consumer row.
Select the Plugins tab.
Click Add Plugin.
Find and select the AWS Lambda plugin.

Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
If the option is available, select Global.
Enter the following parameters, updating the default or sample values as needed:
- Config.Function Name: LAMBDA_FUNCTION_NAME
- Config.Timeout: 60000
- Config.Keepalive: 60000
Click Create.

Enable the plugin globally

A plugin which is not associated to any service, route, or consumer is considered global, and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

Admin API

Kubernetes

Declarative (YAML)

Kong Manager

For example, configure this plugin globally with:

$ curl -X POST http://{HOST}:8001/plugins/ \
    --data "name=aws-lambda"  \
    --data-urlencode "config.aws_key=AWS_KEY" \
    --data-urlencode "config.aws_secret=AWS_SECRET" \
    --data "config.aws_region=AWS_REGION" \
    --data "config.function_name=LAMBDA_FUNCTION_NAME" \
    --data "config.timeout=60000" \
    --data "config.keepalive=60000"

Create a KongClusterPlugin resource and label it as global:

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: <global-aws-lambda>
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: \"true\"
config: 
  aws_key: AWS_KEY
  aws_secret: AWS_SECRET
  aws_region: AWS_REGION
  function_name: LAMBDA_FUNCTION_NAME
  timeout: 60000
  keepalive: 60000
plugin: aws-lambda

For example, configure this plugin using the plugins: entry in the declarative configuration file:

plugins:
- name: aws-lambda
  config: 
    aws_key: AWS_KEY
    aws_secret: AWS_SECRET
    aws_region: AWS_REGION
    function_name: LAMBDA_FUNCTION_NAME
    timeout: 60000
    keepalive: 60000

Configure this plugin globally:

In Kong Manager, select the workspace.
From the Dashboard, select Plugins in the left navigation.
Click New Plugin.
Find and select the AWS Lambda plugin.

Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
If the option is available, set the plugin scope to Global.
Enter the following parameters, updating the default/sample values as needed:
- Config.Function Name: LAMBDA_FUNCTION_NAME
- Config.Timeout: 60000
- Config.Keepalive: 60000
Click Create.

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

Form Parameter	Description
`name` Type: string	The name of the plugin to use, in this case `aws-lambda`.
`service.id` Type: string	The ID of the Service the plugin targets.
`route.id` Type: string	The ID of the Route the plugin targets.
`consumer.id` Type: string	The ID of the Consumer the plugin targets.
`enabled` Type: boolean Default value: `true`	Whether this plugin will be applied.
`config.aws_key` semi-optional	The AWS key credential to be used when invoking the function. This value is required if `aws_secret` is defined. If `aws_key` and `aws_secret` are not set, the plugin uses an IAM role inherited from the instance running Kong to authenticate.
`config.aws_secret` semi-optional	The AWS secret credential to be used when invoking the function. This value is required if `aws_key` is defined. If `aws_key` and `aws_secret` are not set, the plugin uses an IAM role inherited from the instance running Kong to authenticate.
`config.aws_region` semi-optional	The AWS region where the Lambda function is located. The plugin does not attempt to validate the supplied region name; if an invalid region name is provided, the plugin will respond with an HTTP `500 Internal Server Error` at run-time and log a DNS resolution failure. Either `aws_region` or `host` must be provided.
`config.host` semi-optional	The host where the Lambda function is located. This value can point to a local Lambda server, allowing for easier debugging. Either `host` or `aws_region` must be provided.
`config.function_name` required	The AWS Lambda function name to invoke.
`config.qualifier` optional	The `Qualifier` to use when invoking the function.
`config.invocation_type` optional Default value: `RequestResponse`	The `InvocationType` to use when invoking the function. Available types are `RequestResponse`, `Event`, `DryRun`.
`config.log_type` optional Default value: `Tail`	The `LogType` to use when invoking the function. By default, `None` and `Tail` are supported.
`config.timeout` required Default value: `60000`	An optional timeout in milliseconds when invoking the function.
`config.port` optional Default value: `443`	The TCP port that this plugin will use to connect to the server.
`config.keepalive` required Default value: `60000`	An optional value in milliseconds that defines how long an idle connection will live before being closed.
`config.unhandled_status` optional Default value: `200, 202, or 204`	The response status code to use (instead of the default `200`, `202`, or `204`) in the case of an `Unhandled` Function Error.
`config.forward_request_body` optional Default value: `false`	An optional value that defines whether the request body is to be sent in the `request_body` field of the JSON-encoded request. If the body arguments can be parsed, they will be sent in the separate `request_body_args` field of the request. The body arguments can be parsed for `application/json`, `application/x-www-form-urlencoded`, and `multipart/form-data` content types.
`config.forward_request_headers` optional Default value: `false`	An optional value that defines whether the original HTTP request headers are to be sent as a map in the `request_headers` field of the JSON-encoded request.
`config.forward_request_method` optional Default value: `false`	An optional value that defines whether the original HTTP request method verb is to be sent in the `request_method` field of the JSON-encoded request.
`config.forward_request_uri` optional Default value: `false`	An optional value that defines whether the original HTTP request URI is to be sent in the `request_uri` field of the JSON-encoded request. Request URI arguments (if any) will be sent in the separate `request_uri_args` field of the JSON body.
`config.is_proxy_integration` optional Default value: `false`	An optional value that defines whether the response format to receive from the Lambda to this format. Note that the parameter `isBase64Encoded` is not implemented.
`config.awsgateway_compatible` optional Default value: `false`	An optional value that defines whether the plugin should wrap requests into the Amazon API gateway.
`config.proxy_url` semi-optional	An optional value that defines whether the plugin should connect through the given proxy server URL. This value is required if `proxy_scheme` is defined.
`config.proxy_scheme` semi-optional	An optional value that defines which HTTP scheme to use for connecting through the proxy server. The schemes supported are: `http` and `https`. This value is required if `proxy_url` is defined.
`config.skip_large_bodies` optional Default value: `true`	An optional value that defines whether Kong should send large bodies that are buffered to disk. To define the threshold for the body size, use the client_body_buffer_size property. Note that sending large bodies will have an impact on system memory.

Reminder: By default, cURL sends payloads with an application/x-www-form-urlencoded MIME type, which will naturally be URL- decoded by Kong. To ensure special characters that are likely to appear in your AWS key or secret (like +) are correctly decoded, you must URL-encode them with --data-urlencode. Alternatives to this approach would be to send your payload with a different MIME type (like application/json), or to use a different HTTP client.

Sending parameters

Any form parameter sent along with the request will be also sent as an argument to the AWS Lambda function.

Notes

If you do not provide an aws_key and aws_secret, the plugin uses an IAM role inherited from the instance running Kong.

First, the plugin will try ECS metadata to get the role. If no ECS metadata is available, the plugin will fall back on EC2 metadata.

Known Issues

Use a fake upstream service

When using the AWS Lambda plugin, the response will be returned by the plugin itself without proxying the request to any upstream service. This means that a Service’s host, port, and path properties will be ignored, but must still be specified for the entity to be validated by Kong. The host property in particular must either be an IP address, or a hostname that gets resolved by your nameserver.

Response plugins

There is a known limitation in the system that prevents some response plugins from being executed. We are planning to remove this limitation in the future.

Step-By-Step Guide

Steps

Prerequisite: You must have access to the AWS Console as a user who is allowed to operate with lambda functions, and create users and roles.

Create an Execution role in AWS.
Create a user that will invoke the function via Kong and test it.
Create a Service and Route in Kong, add the aws-lambda plugin linked to our AWS function, and execute it.

Configure

First, create an execution role called LambdaExecutor for your lambda function.

In the IAM Console, create a new Role choosing the AWS Lambda service. There will be no policies because the function in this example will simply execute itself, returning a hardcoded JSON response without accessing other AWS resources.
Create a user named KongInvoker, used by the Kong API gateway to invoke the function.

In the IAM Console, create a new user. Programmatic access must be provided to the user via Access and Secret keys. Then, attach existing policies directly, particularly the predefined AWSLambdaRole. After the user creation is confirmed, store the Access Key and Secret Key in a safe place.
Next, create the lambda function itself in the N. Virginia Region (code us-east-1).

In Lambda Management, create a new function MyLambda. There will be no blueprint because you are going to paste the code below (which is an example code snippet). For the execution role, choose the LambdaExecutor created previously.

Note: The following code snippet is only an example. The Kong AWS Lambda plugin supports all runtimes provided by AWS. See the list of runtimes in the AWS Lambda > Functions > Create function dialog.
```
 import json
 def lambda_handler(event, context):
     """
       If is_proxy_integration is set to true :
       jsonbody='''{"statusCode": 200, "body": {"response": "yes"}}'''
     """
     jsonbody='''{"response": "yes"}'''
     return json.loads(jsonbody)
```
Test the lambda function from the AWS console and make sure the execution succeeds.
Set up a Service and Route in Kong and link it to the MyLambda function you just created.

With a database

Without a database

curl -i -X POST http://{kong_hostname}:8001/services \
--data 'name=lambda1' \
--data 'url=http://localhost:8000' \

The Service doesn’t really need a real url because this example won’t have an HTTP call to an Upstream but rather a response generated by the lambda function.

Also create a Route for the Service:

curl -i -X POST http://{kong_hostname}:8001/services/lambda1/routes \
--data 'paths[1]=/lambda1'

Add the plugin:

curl -i -X POST http://{kong_hostname}:8001/services/lambda1/plugins \
--data 'name=aws-lambda' \
--data-urlencode 'config.aws_key={KongInvoker user key}' \
--data-urlencode 'config.aws_secret={KongInvoker user secret}' \
--data 'config.aws_region=us-east-1' \
--data 'config.function_name=MyLambda'

Add a Service, Route, and Plugin to the declarative config file:

services:
- name: lambda1
  url: http://localhost:8000

routes:
- service: lambda1
  paths: [ "/lambda1" ]

plugins:
- service: lambda1
  name: aws-lambda
  config:
    aws_key: {KongInvoker user key}
    aws_secret: {KongInvoker user secret}
    aws_region: us-east-1
    function_name: MyLambda

After everything is created, call the Service and verify the correct invocation, execution, and response:

curl http://{kong_hostname}:8000/lambda1

Additional headers:

x-amzn-Remapped-Content-Length, X-Amzn-Trace-Id, x-amzn-RequestId

JSON response:

{"response": "yes"}

Have fun leveraging the power of AWS Lambda in Kong!

About this Plugin
Made by
Categories	Serverless
DB-less compatible?	Yes
Konnect tier
Konnect Cloud	See latest plugin version for availability
Version Compatibility
Kong Gateway (Enterprise) 2.1.x 1.5.x 1.3-x 0.36-x 0.35-x 0.34-x 0.33-x 0.32-x 0.31-x Kong Gateway (OSS) 2.1.x 2.0.x 1.5.x 1.4.x 1.3.x 1.2.x 1.1.x 1.0.x 0.14.x 0.13.x 0.12.x 0.11.x 0.10.x