Document updated on Jun 20, 2023
Since | v1.0 |
---|---|
Namespace | backend/lambda |
Scope | backend |
Source | krakend/krakend-lambda |
The Lambda integration allows you to invoke Amazon Lambda functions on a KrakenD endpoint call. The content returned by the lambda function can be treated and manipulated as any other backend.
The payload that is sent to the Lambda function comes from the request and depends on the method used by the endpoint
:
GET
: The payload contains all the request parameters.GET
methods: The payload is defined by the content of the body in the request.You don’t need to set an Amazon API Gateway in the middle, as KrakenD does this job for you.
host
and url_pattern
are needed as per the backend definition, but KrakenD will never use them when connecting to a Lambda. Feel free to add any value in there, but the entry must be present.The inclusion requires you to add the code in the extra_config
of your backend
section using the backend/lambda
namespace.
The supported parameters are:
| An optional parameter to customize the Lambda endpoint to call. Useful when Localstack is used for testing instead of direct AWS usage. |
| Name of the lambda function as saved in the AWS service. You have to choose between function_name and function_param_name but not both. |
| The endpoint {placeholder} that sets the function name, with the first letter uppercased. You have to choose between function_name and function_param_name but not both. If your endpoint defines the route /foo/{bar} the value of function_param_name must be Bar with the uppercased B. |
| Maximum times you want to execute the function until you have a successful response. The value -1 defers the max retry setting to the service specific configuration. Defaults to 0 |
| The AWS identifier region Examples: "us-east-1" , "eu-west-2" |
{route}
, define it in the config as Route
.When passing the lambda function name, you can use any of the following formats:
my-function
my-function:v1
arn:aws:lambda:us-west-2:123456789012:function:my-function
123456789012:function:my-function
The KrakenD machine needs connectivity with your AWS account and the credentials to do so. There are several ways you can achieve this:
~/.aws/credentials
(and maybe an additional ~/.aws/config
and the env var AWS_PROFILE
if you have several profiles)AWS_ACCESS_KEY_ID
and AWS_SECRET_ACCESS_KEY
(and maybe AWS_REGION
) when starting KrakenD.When setting the credentials, ensure the Lambda is callable within the KrakenD box with the selected method.
If your machine has the AWS CLI installed, you can test your Lambda:
$aws lambda invoke --region us-east-1 --function-name myLambdaFunction --output json result.json
Mounting an existing .aws
directory with the credentials in it (notice that the home of the Docker user is krakend
):
$docker run --rm -it -p "8080:8080" \
-e "AWS_PROFILE=default" \
-v "/home/user/.aws:/home/krakend/.aws:ro" \
-v "$PWD:/etc/krakend" devopsfaith/krakend:2.6
Passing the credentials directly:
$docker run --rm -it -p "8080:8080" \
-e "AWS_ACCESS_KEY_ID=XXX" \
-e "AWS_SECRET_ACCESS_KEY=XXX" \
-e "AWS_REGION=eu-west-1" \
-v "$PWD:/etc/krakend" devopsfaith/krakend:2.6
The official library of AWS has a limitation preventing KrakenD from sending any headers, yet it is impossible to forward them even when you add them under input_headers
.
If you require such functionality, you should create a custom payload (like this one) with additional data containing the headers (and anything else than the body itself).
You can easily do Canary or A/B testing with Lambda functions in combination with a Lua script like the one provided below.
For example, the following configuration takes the function name from a parameter that is not defined anywhere. Instead, a Lua script will set it as per our AB test or canary rules.
The configuration would be:
{
"endpoint": "/call-a-lambda",
"backend": [
{
"host": ["ignore"],
"url_pattern": "/ignore",
"extra_config": {
"backend/lambda": {
"function_param_name": "Function_name",
"region": "eu-west-1",
"max_retries": 1
},
"modifier/lua-backend": {
"sources": ["canary.lua"],
"pre": "canaryLambda(request.load())",
"allow_open_libs": true
}
}
}
]
}
And the content of the canary.lua
file would be:
function canaryLambda( req )
local rand = math.random(0, 100)
if rand < 20
then
req:params("Function_name", "my-function:3")
else
req:params("Function_name", "my-function:2")
end
end
As you can read from the code, 20% of the requests will invoke my-function:3
, while the 80% remaining will fall into the older my-function:2
.
For more Canary Release examples (not only Lambda) see this blog post
When you associate a KrakenD endpoint to a unique lambda function, use this configuration:
{
"endpoint": "/call-a-lambda",
"backend": [
{
"host": ["ignore"],
"url_pattern": "/ignore",
"extra_config": {
"backend/lambda": {
"function_name": "myLambdaFunction",
"region": "us-east-1",
"max_retries": 1
}
}
}
]
}
Here is an example of Lambda code that could run a Hello World (NodeJS):
exports.handler = async (event) => {
// TODO implement
const response = {
"message": "Hello World",
};
return response;
};
When the name of the Lambda depends on a parameter passed in the endpoint, use this configuration instead:
{
"endpoint": "/call-a-lambda/{lambda}",
"backend": [
{
"host": ["ignore"],
"url_pattern": "/ignore",
"extra_config": {
"backend/lambda": {
"function_param_name": "Lambda",
"region": "us-west1",
"max_retries": 1
}
}
}
]
}
In this example, the function_param_name
tells us which is the placeholder in the endpoint setting the Lambda. In this case, {lambda}
.
Following the code, a call GET /call-a-lambda/my-lambda
would produce a call to the My-lambda
function in AWS.
The documentation is only a piece of the help you can get! Whether you are looking for Open Source or Enterprise support, see more support channels that can help you.