AWS Lambda

This plugin lets you invoke an AWS Lambda function from Kong Gateway. The AWS Lambda plugin can be used in combination with other request plugins to secure, manage, or extend the function.

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

The AWS Lambda plugin will automatically fetch the IAM role credential according to the following precedence order:

1. Fetch from the credentials defined in the config.aws_key and config.aws_secret parameters in the plugin configuration.

   By default, cURL sends payloads with an application/x-www-form-urlencoded MIME type, which will naturally be URL-decoded by Kong Gateway. 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.

2. Fetch from the credentials defined in the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.
3. Fetch from the profile and credential file, defined by AWS_PROFILE and AWS_SHARED_CREDENTIALS_FILE.
4. Fetch from the ECS container credential provider.
5. Fetch from the EKS IAM roles for the service account.
6. Fetch from the EC2 IMDS metadata. Both v1 and v2 are supported.

Note: IAM Identity Center credential provider and Process credential provider are not supported.

If you also specify the config.aws_assume_role_arn parameter, the plugin will try to perform an additional AssumeRole action. This requires the Kong Gateway process to make an HTTPS request to the AWS STS service API after configuring the AWS access key/secret or fetching credentials automatically from EC2/ECS/EKS IAM roles. If it succeeds, the plugin will fetch temporary security credentials that give the plugin the access permission configured in the target assumed role. The plugin will then try to invoke the Lambda function based on the target assumed role.

If the config.aws_region parameter isn’t specified, the plugin attempts to get the AWS region through the environment variables AWS_REGION and AWS_DEFAULT_REGION, in that order. If none of these are set, a runtime error no region or host specified will be thrown.

By default, when the Lambda Invoke API rejects a call before the function runs (for example, a 400 Bad Request or 403 Forbidden), Kong Gateway returns a generic HTTP 500 to the client. This makes it difficult to distinguish authorization failures from bad requests.

You can enable config.preserve_lambda_api_error_code to return the original 4xx or 5xx status code from the Lambda API instead. This setting only applies when the Lambda Invoke API itself returns status >= 400, and doesn’t affect errors raised inside a successfully invoked function.

Response sanitization

Kong Gateway sanitizes the client response body to {"message":"Upstream Lambda invocation failed"} and never exposes AWS error messages or ARNs to clients.

If the Kong Gateway log level is set to error, it logs the full error detail regardless of this setting. For example:

AWS Lambda API returned error: <msg>, status code: <code>`.