Invoke an AWS Lambda function from Kong. The AWS Lambda plugin can be used in combination with other request plugins to secure, manage, or extend the function.
Configuration Reference
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
Example plugin configuration
Parameters
Here's a list of all the parameters which can be used in this plugin's configuration:
Form Parameter | Description |
---|---|
name
required Type: string |
The name of the plugin, in this case aws-lambda . |
instance_name
optional Type: string |
An optional custom name to identify an instance of the plugin, for example Useful when running the same plugin in multiple contexts, for example, on multiple services. |
service.name or service.id
optional Type: string |
The name or ID of the service the plugin targets. Set one of these parameters if adding the plugin to a service through the top-level Not required if using |
route.name or route.id
optional Type: string |
The name or ID of the route the plugin targets. Set one of these parameters if adding the plugin to a route through the top-level Not required if using |
consumer.name or consumer.id
optional
|
The name or ID of the consumer the plugin targets. Set one of these parameters if adding the plugin to a consumer through the top-level Not required if using |
enabled
optional Type: boolean Default value: |
Whether this plugin will be applied. |
config.aws_key
semi-optional Type: string |
The AWS key credential to be used when invoking the function. The If keyring database encryption is enabled, this value will be encrypted. This field is referenceable, which means it can be securely stored as a secret in a vault. References must follow a specific format. |
config.aws_secret
semi-optional Type: string |
The AWS secret credential to be used when invoking the function. The If keyring database encryption is enabled, this value will be encrypted. This field is referenceable, which means it can be securely stored as a secret in a vault. References must follow a specific format. |
config.aws_region
semi-optional Type: string |
The AWS region where the Lambda function is located. The plugin does not attempt to validate the supplied region name. The plugin has two methods of detecting the AWS region: the If The AWS region is required for AWS SigV4.
If |
config.aws_assume_role_arn
optional Type: string |
The target AWS IAM role ARN used to invoke the Lambda function. Typically this is used for a cross-account Lambda function invocation. This field is referenceable, which means it can be securely stored as a secret in a vault. References must follow a specific format. |
config.aws_role_session_name
optional Type: string Default value: |
The identifier of the assumed role session. It is used for uniquely identifying a session when the same target role is assumed by different principals or for different reasons. The role session name is also used in the ARN of the assumed role principle. |
config.host
optional Type: string |
The host where the Lambda function is located. This value can point to a local Lambda server, allowing for easier debugging. To set a region, use the |
config.function_name
required Type: string |
The AWS Lambda function name to invoke. This may contain
the function name only ( |
config.qualifier
optional Type: string |
The |
config.invocation_type
required Type: string Default value: |
The |
config.log_type
required Type: string Default value: |
The |
config.timeout
required Type: number Default value: |
An optional timeout in milliseconds when invoking the function. |
config.port
optional Type: integer Default value: |
The TCP port that the plugin uses to connect to the server. |
config.keepalive
required Type: number Default value: |
An optional value in milliseconds that defines how long an idle connection lives before being closed. |
config.unhandled_status
optional Type: integer Default value: |
The response status code to use (instead of the default |
config.forward_request_body
optional Type: boolean Default value: |
An optional value that defines whether the request body is sent in the |
config.forward_request_headers
optional Type: boolean Default value: |
An optional value that defines whether the original HTTP request headers are
sent as a map in the |
config.forward_request_method
optional Type: boolean Default value: |
An optional value that defines whether the original HTTP request method verb is
sent in the |
config.forward_request_uri
optional Type: boolean Default value: |
An optional value that defines whether the original HTTP request URI is sent in
the |
config.is_proxy_integration
optional Type: boolean Default value: |
An optional value that defines whether the response format to receive from the Lambda to this format. |
config.awsgateway_compatible
optional Type: boolean Default value: |
An optional value that defines whether the plugin should wrap requests into the Amazon API gateway. |
config.proxy_url
semi-optional Type: string |
An optional value that defines whether the plugin should connect through
the given proxy server URL. Include the request scheme in the URL, which
must be Kong Gateway uses HTTP tunneling via the CONNECT HTTP method so that no details of the AWS Lambda request are leaked to the proxy server. |
config.skip_large_bodies
optional Type: boolean Default value: |
An optional value that defines whether Kong should send large bodies that are buffered to disk. Note that enabling this option will have an impact on system memory depending on the number of requests simultaneously in flight at any given point in time and on the maximum size of each request. Also this option blocks all requests being handled by the nginx workers. That could be tens of thousands of other transactions that are not being processed. For small I/O operations, such a delay would generally not be problematic. In cases where the body size is in the order of MB, such a delay would cause notable interruptions in request processing. Given all of the potential downsides resulting from enabling this option, consider increasing the client_body_buffer_size value instead. |
config.base64_encode_body
optional Type: boolean Default value: |
An optional value that Base64-encodes the request body. |
config.aws_imds_protocol_version
required Type: string Default value: |
Identifier to select the IMDS protocol version to use, either
|
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 is also sent as an argument to the AWS Lambda function.
Notes
If you provide aws_key
and aws_secret
, they will be used in the highest priority to
invoke the Lambda function.
If you do not provide an aws_key
and aws_secret
, the plugin uses an IAM role inherited
from the instance running Kong.
For example, if you’re running Kong on an EC2 instance, the IAM role that attached to the EC2 will be used, and Kong will fetch the credential from the EC2 Instance Metadata service(IMDSv1). If you’re running Kong in an ECS container, the task IAM role will be used, and Kong will fetch the credentials from the container credential provider. Note that the plugin will first try to fetch from ECS metadata to get the role, and if no ECS metadata related environment variables are available, the plugin falls back on EC2 metadata.
If you also provide the aws_assume_role_arn
option, the plugin will try to perform
an additional AssumeRole
action, which requires the Kong process to make HTTPS request to AWS STS service API, after
configuring AWS access key/secret or fetching credentials automatically from EC2/ECS IAM roles.
If it succeeds, the plugin will fetch a temporary security credentials that represents
that the plugin now has the access permission configured in the target assumed role.
AWS region as environment variable
If the plugin configuration aws_region
is unset, the plugin attempts to obtain the
AWS region through environment variables AWS_REGION
and AWS_DEFAULT_REGION
,
with the former taking higher precedence. For example, if both AWS_REGION
and
AWS_DEFAULT_REGION
are set, the AWS_REGION
value is used; otherwise, if only
AWS_DEFAULT_REGION
is set, its value is used. If neither configuration aws_region
nor environment variables are set, a run-time error “no region or host specified”
will be thrown.
Usage
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.
-
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 theLambdaExecutor
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 route in Kong and link it to the
MyLambda
function you just created.
Test your Lambda with Kong
After everything is created, make the http request 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!
Changelog
Kong Gateway 3.1.x
- Added a
requestContext
field intoawsgateway_compatible
input data. #9380
Kong Gateway 3.0.x
- The
proxy_scheme
configuration parameter has been removed from the plugin. - The plugin now allows both
aws_region
andhost
to be set at the same time.
Kong Gateway 2.8.x
- The
proxy_scheme
configuration parameter is deprecated and planned to be removed in 3.x.x. - Kong Gateway 2.8.1.3: Added support for cross account invocation
through configuration properties
aws_assume_role_arn
andaws_role_session_name
.
Kong Gateway 2.7.x
- Starting with Kong Gateway 2.7.0.0, if keyring encryption is enabled,
the
config.aws_key
andconfig.aws_secret
parameter values will be encrypted.
Kong Gateway 2.6.x
- The AWS region can now be set with the environment variables:
AWS_REGION
orAWS_DEFAULT_REGION
.
Kong Gateway 2.2.x
- Added support for
isBase64Encoded
flag in Lambda function responses.
Kong Gateway 2.1.x
- Added
host
configuration to allow for custom Lambda endpoints.