Tutorial: Building a custom runtime

To create an execution role

1. Open the roles page in the IAM console.

2. Choose Create role.

3. Create a role with the following properties.

   • Trusted entity – Lambda.

   • Permissions – AWSLambdaBasicExecutionRole.

   • Role name – lambda-role.

   The AWSLambdaBasicExecutionRole policy has the permissions that the function needs to write logs to CloudWatch Logs.

1. Create a directory for the project, and then switch to that directory.

   mkdir runtime-tutorial
   cd runtime-tutorial

2. Create a new file called bootstrap. This is the custom runtime.

   Example bootstrap

   #!/bin/sh
   
   set -euo pipefail
   
   # Initialization - load function handler
   source $LAMBDA_TASK_ROOT/"$(echo $_HANDLER | cut -d. -f1).sh"
   
   # Processing
   while true
   do
     HEADERS="$(mktemp)"
     # Get an event. The HTTP request will block until one is received
     EVENT_DATA=$(curl -sS -LD "$HEADERS" "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next")
   
     # Extract request ID by scraping response headers received above
     REQUEST_ID=$(grep -Fi Lambda-Runtime-Aws-Request-Id "$HEADERS" | tr -d '[:space:]' | cut -d: -f2)
   
     # Run the handler function from the script
     RESPONSE=$($(echo "$_HANDLER" | cut -d. -f2) "$EVENT_DATA")
   
     # Send the response
     curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response"  -d "$RESPONSE"
   done

   The runtime loads a function script from the deployment package. It uses two variables to locate the script. LAMBDA_TASK_ROOT tells it where the package was extracted, and _HANDLER includes the name of the script.

   After the runtime loads the function script, it uses the runtime API to retrieve an invocation event from Lambda, passes the event to the handler, and posts the response back to Lambda. To get the request ID, the runtime saves the headers from the API response to a temporary file, and reads the Lambda-Runtime-Aws-Request-Id header from the file.

   Note

   Runtimes have additional responsibilities, including error handling, and providing context information to the handler. For details, see Requirements.

3. Create a script for the function. The following example script defines a handler function that takes event data, logs it to stderr, and returns it.

   Example function.sh

   function handler () {
     EVENT_DATA=$1
     echo "$EVENT_DATA" 1>&2;
     RESPONSE="Echoing request: '$EVENT_DATA'"
   
     echo $RESPONSE
   }

   The runtime-tutorial directory should now look like this:

   runtime-tutorial
   ├ bootstrap
   └ function.sh

4. Make the files executable and add them to a .zip file archive. This is the deployment package.

   chmod 755 function.sh bootstrap
   zip function.zip function.sh bootstrap

5. Create a function named bash-runtime. For --role, enter the ARN of your Lambda execution role.

   aws lambda create-function --function-name bash-runtime \
   --zip-file fileb://function.zip --handler function.handler --runtime provided.al2023 \
   --role arn:aws:iam::123456789012:role/lambda-role

6. Invoke the function.

   aws lambda invoke --function-name bash-runtime --payload '{"text":"Hello"}' response.txt --cli-binary-format raw-in-base64-out

   The cli-binary-format option is required if you're using AWS CLI version 2. To make this the default setting, run aws configure set cli-binary-format raw-in-base64-out. For more information, see AWS CLI supported global command line options in the AWS Command Line Interface User Guide for Version 2.

   You should see a response like this:

   {
       "StatusCode": 200,
       "ExecutedVersion": "$LATEST"
   }

7. Verify the response.

   cat response.txt

   You should see a response like this:

   Echoing request: '{"text":"Hello"}'

1. Create a .zip file that contains the bootstrap file.

   zip runtime.zip bootstrap

2. Create a layer with the publish-layer-version command.

   aws lambda publish-layer-version --layer-name bash-runtime --zip-file fileb://runtime.zip

   This creates the first version of the layer.

1. Update the function configuration to pull in the layer.

   aws lambda update-function-configuration --function-name bash-runtime \
   --layers arn:aws:lambda:us-east-1:123456789012:layer:bash-runtime:1

   This adds the runtime to the function in the /opt directory. To ensure that Lambda uses the runtime in the layer, you must remove the boostrap from the function's deployment package, as shown in the next two steps.

2. Create a .zip file that contains the function code.

   zip function-only.zip function.sh

3. Update the function code to only include the handler script.

   aws lambda update-function-code --function-name bash-runtime --zip-file fileb://function-only.zip

4. Invoke the function to confirm that it works with the runtime layer.

   aws lambda invoke --function-name bash-runtime --payload '{"text":"Hello"}' response.txt --cli-binary-format raw-in-base64-out

   The cli-binary-format option is required if you're using AWS CLI version 2. To make this the default setting, run aws configure set cli-binary-format raw-in-base64-out. For more information, see AWS CLI supported global command line options in the AWS Command Line Interface User Guide for Version 2.

   You should see a response like this:

   {
       "StatusCode": 200,
       "ExecutedVersion": "$LATEST"
   }

5. Verify the response.

   cat response.txt

   You should see a response like this:

   Echoing request: '{"text":"Hello"}'

1. To log information about the execution environment, update the runtime script to output environment variables.

   Example bootstrap

   #!/bin/sh
   
   set -euo pipefail
   
   # Configure runtime to output environment variables
   echo "##  Environment variables:"
   env
   
   # Load function handler
   source $LAMBDA_TASK_ROOT/"$(echo $_HANDLER | cut -d. -f1).sh"
   
   # Processing
   while true
   do
     HEADERS="$(mktemp)"
     # Get an event. The HTTP request will block until one is received
     EVENT_DATA=$(curl -sS -LD "$HEADERS" "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next")
   
     # Extract request ID by scraping response headers received above
     REQUEST_ID=$(grep -Fi Lambda-Runtime-Aws-Request-Id "$HEADERS" | tr -d '[:space:]' | cut -d: -f2)
   
     # Run the handler function from the script
     RESPONSE=$($(echo "$_HANDLER" | cut -d. -f2) "$EVENT_DATA")
   
     # Send the response
     curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response"  -d "$RESPONSE"
   done

2. Create a .zip file that contains the new version of the bootstrap file.

   zip runtime.zip bootstrap

3. Create a new version of the bash-runtime layer.

   aws lambda publish-layer-version --layer-name bash-runtime --zip-file fileb://runtime.zip

4. Configure the function to use the new version of the layer.

   aws lambda update-function-configuration --function-name bash-runtime \
   --layers arn:aws:lambda:us-east-1:123456789012:layer:bash-runtime:2