Tutorial: Creating a Bash runtime
In this tutorial, you write a minimal runtime interface client (RIC) in Bash. You build the RIC into a runtime image, and create a customer-managed runtime from the image. Then you create and invoke a Lambda Event Function that uses the runtime.
The tutorial shows how a runtime uses the Lambda runtime API. Use the same approach to add support for a new language. For the requirements that every runtime must meet, see Supporting a new programming language for AWS Lambda Event Functions. For the API that the runtime calls, see Using the Lambda runtime API. For what goes into a runtime image, see Building runtime images.
Some steps are the same as in the main customer-managed runtime tutorial. For the basic steps on a Lambda base image, including how to update a runtime, see Tutorial: Creating and using a customer-managed runtime.
Cost to complete – There's no additional charge for customer-managed runtimes. Standard Lambda charges apply to function invocations, and standard Amazon ECR storage charges apply to the runtime image. To avoid ongoing charges, complete the steps in Clean up.
Prerequisites
This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda console. If you haven't already, follow the instructions in Create a Lambda function with the console to create your first Lambda function.
To complete the following steps, you need the AWS CLI version 2. Commands and the expected output are listed in separate blocks:
aws --version
You should see the following output:
aws-cli/2.13.27 Python/3.11.6 Linux/4.14.328-248.540.amzn2.x86_64 exe/x86_64.amzn.2
For long commands, an escape character (\) is used to split a command over multiple lines.
On Linux and macOS, use your preferred shell and package manager.
In Windows, some Bash CLI commands that you commonly use with Lambda (such as zip) are not supported by the operating system's built-in terminals.
To get a Windows-integrated version of Ubuntu and Bash, install the Windows Subsystem for Linux
You also need the following:
-
The AWS CLI version 2.40.3 or later. To check your version, run
aws --version. To install or update the AWS CLI, see Installing or updating to the latest version of the AWS CLI in the AWS Command Line Interface User Guide. -
The Docker CLI
, or a compatible tool such as Podman. The commands in this tutorial use Docker. -
IAM permissions to create and delete runtimes, runtime versions, and runtime aliases. To create a runtime version, you also need
ecr:BatchGetImageandecr:GetDownloadUrlForLayeron the Amazon ECR repository that contains the image. For the full list of IAM actions, see IAM actions. -
IAM permissions to use the runtime alias in a function, including
lambda:AssociateRuntimeAlias. For more information, see Before you begin. -
Permissions to create and delete Amazon ECR repositories and Lambda functions.
-
IAM permissions to create and delete the function's execution role, and to pass the role to Lambda:
iam:CreateRole,iam:AttachRolePolicy,iam:PassRole,iam:DetachRolePolicy, andiam:DeleteRole.
How the Bash runtime works
The runtime in this tutorial has one part: a Bash script named bootstrap. The bootstrap script is the RIC. The script links the function code to Lambda through the runtime API.
The runtime image starts from the Lambda OS-only base image, provided:al2023. The base image's ENTRYPOINT is /lambda-entrypoint.sh. When Lambda starts an execution environment, /lambda-entrypoint.sh sets the _HANDLER environment variable to the function's handler. Then /lambda-entrypoint.sh runs /var/runtime/bootstrap. For more information, see Choosing an entrypoint.
The runtime defines the handler format. The Bash runtime uses the format . For example, the handler file.functionfunction.handler refers to the handler function in the function.sh file.
The bootstrap script does the following:
-
Reads the file name from
_HANDLER, and loads$LAMBDA_TASK_ROOT/. Lambda extracts the function code to the directory infile.shLAMBDA_TASK_ROOT. -
Sends a
GETrequest to the/runtime/invocation/nextpath to get the next invocation event. The request waits until an event is available. For more information, see Next invocation. -
Reads the
Lambda-Runtime-Aws-Request-Idheader and theLambda-Runtime-Invocation-Idheader from the response. -
Calls the handler function with the event data.
-
Sends the handler output in a
POSTrequest to the/runtime/invocation/path. The request includes theAwsRequestId/responseLambda-Runtime-Invocation-Idheader with the value from step 3. For more information, see Invocation response. -
Returns to step 2 for the next event.
The Bash runtime is a minimal example. The bootstrap script doesn't report errors to Lambda, and doesn't provide context information to the handler. A production runtime reports errors with the Initialization error and Invocation error methods. For all runtime responsibilities, see Requirements.
Step 1: Create an execution role
The function that you create later in this tutorial needs an execution role. Create the role first, because a new role can take a few seconds to become available.
In this tutorial, you create a role that grants only basic permissions: the AWSLambdaBasicExecutionRole managed policy lets the function write logs to Amazon CloudWatch Logs. If your function needs to call other AWS services, add the permissions that it needs to the role, or use a different execution role. For more information, see Defining Lambda Event Function permissions with an execution role.
To create an execution role
-
To create a role named
bash-tutorial-rolethat Lambda can assume, run thecreate-rolecommand.aws iam create-role \ --role-name bash-tutorial-role \ --assume-role-policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"lambda.amazonaws.com"},"Action":"sts:AssumeRole"}]}' -
To allow the function to write logs, attach the
AWSLambdaBasicExecutionRolemanaged policy to the role.aws iam attach-role-policy \ --role-name bash-tutorial-role \ --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
Step 2: Write the runtime interface client
Create the bootstrap script. In the next step, you install the script at /var/runtime/bootstrap in the runtime image.
To write the runtime interface client
-
Create a directory for the project, and change to the directory.
mkdir bash-runtime-tutorial && cd bash-runtime-tutorial -
Create a file named
bootstrapwith the following content:#!/bin/bash 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) # Extract invocation ID for cross-wiring protection, if present INVOCATION_ID=$(grep -Fi Lambda-Runtime-Invocation-Id "$HEADERS" | tr -d '[:space:]' | cut -d: -f2 || true) # Run the handler function from the script RESPONSE=$($(echo "$_HANDLER" | cut -d. -f2) "$EVENT_DATA") # Send the response, echoing the invocation ID curl -sS "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/response" -d "$RESPONSE" \ ${INVOCATION_ID:+--header "Lambda-Runtime-Invocation-Id: $INVOCATION_ID"} # Remove the temporary headers file rm -f "$HEADERS" doneThe script gets the endpoint of the runtime API from the
AWS_LAMBDA_RUNTIME_APIenvironment variable. To get the request ID, the script saves the response headers to a temporary file, and then reads theLambda-Runtime-Aws-Request-Idheader from the file. After it sends the response, the script deletes the file. TheLambda-Runtime-Invocation-Idheader might not be present, for example when you test the runtime locally with the runtime interface emulator. In that case, the script continues without it.
Step 3: Build and push the runtime image
Each runtime version gets its contents from a container image in Amazon Elastic Container Registry (Amazon ECR). The runtime image in this tutorial adds the bootstrap script to the OS-only base image. For more information about building runtime images without a Lambda language base image, see Building runtime images from scratch.
To build the runtime image
-
Create a file named
Dockerfilewith the following content:FROM public.ecr.aws/lambda/provided:al2023 # Install the runtime interface client. COPY bootstrap /var/runtime/bootstrap RUN chmod 755 /var/runtime/bootstrap # Keep the inherited ENTRYPOINT, /lambda-entrypoint.sh. Don't set CMD.The runtime image inherits the base image's
ENTRYPOINT, which runs/var/runtime/bootstrap. -
Set shell variables for your account ID, your AWS Region, and your Amazon ECR repository URI. Replace
123456789012with your account ID, andus-east-1with the Region that you want to use.export ACCOUNT_ID=123456789012export AWS_REGION=us-east-1export REPO_URI=${ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/bash-runtimeThe AWS CLI sends requests to the Region in the
AWS_REGIONenvironment variable. The runtime, the Amazon ECR repository, and the function must all be in the same Region. Run the remaining commands in the same shell session. -
To build the runtime image, run the
docker buildcommand.docker build --platform linux/amd64 --tag ${REPO_URI}:v1 .The
--platform linux/amd64option builds an x86_64 image on any computer.
Next, create an Amazon ECR repository, allow Lambda to read from the repository, and push the runtime image. For more information, see Amazon ECR requirements.
To push the runtime image to Amazon ECR
-
To create a repository named
bash-runtime, run thecreate-repositorycommand.aws ecr create-repository --repository-name bash-runtime -
Create a file named
ecr-policy.jsonwith the following content. The repository policy allows the Lambda service principal to read images from the repository.{ "Version": "2012-10-17", "Statement": [ { "Sid": "LambdaReadAccess", "Effect": "Allow", "Principal": { "Service": "lambda.amazonaws.com" }, "Action": [ "ecr:BatchGetImage", "ecr:DescribeImages", "ecr:GetDownloadUrlForLayer" ] } ] } -
To apply the policy to the repository, run the
set-repository-policycommand.aws ecr set-repository-policy \ --repository-name bash-runtime \ --policy-text file://ecr-policy.json -
To authenticate Docker to your Amazon ECR registry, run the following command.
aws ecr get-login-password | docker login \ --username AWS \ --password-stdin ${ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.comYou should see the message
Login Succeeded. -
To upload the runtime image, run the
docker pushcommand.docker push ${REPO_URI}:v1
Step 4: Create the runtime, runtime version, and alias
Functions use a customer-managed runtime through three resources. The runtime is the parent resource. A runtime version points to one runtime image. A runtime alias points to one runtime version. For more information, see Creating a runtime, Runtime versions, and Runtime aliases.
To create the runtime
-
To create a runtime named
bash-runtime, run thecreate-runtimecommand.aws lambda-core create-runtime \ --name bash-runtime \ --description "Minimal Bash runtime"You should see output similar to the following:
{ "Arn": "arn:aws:lambda:us-east-1:123456789012:runtime/bash-runtime", "Name": "bash-runtime", "Description": "Minimal Bash runtime", "LicenseInfo": "", "Created": "2026-10-08T09:00:00.000Z", "LastModified": "2026-10-08T09:00:00.000Z" } -
To save the runtime ARN in a shell variable for later steps, run the
get-runtimecommand.export RUNTIME_ARN=$(aws lambda-core get-runtime \ --runtime-name bash-runtime \ --query Arn \ --output text) echo ${RUNTIME_ARN}
To create a runtime version
-
To create a runtime version named
v1from the runtime image, run thecreate-runtime-versioncommand.aws lambda-core create-runtime-version \ --runtime-name bash-runtime \ --name v1 \ --image-uri ${REPO_URI}:v1The following example shows an excerpt of the output. Lambda resolves the image tag to a digest and reads the platform (architecture and OS) from the runtime image.
{ "Name": "v1", "Arn": "arn:aws:lambda:us-east-1:123456789012:runtime/bash-runtime/version/v1", "ResolvedUri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/bash-runtime@sha256:0a1afafd0777718289b2301be0926e267ef17bd9440521e141d51364e7a5fbb5", "State": "CREATING", "Platforms": [ { "Architecture": "amd64", "Os": "linux", "Digest": "sha256:0a1afafd0777718289b2301be0926e267ef17bd9440521e141d51364e7a5fbb5" } ], "Compatibility": { "IntegrationModels": [ "RuntimeAPI" ], "Architectures": [ "x86_64" ], "ManagedInstances": "NotSupported" } } -
To wait until the runtime version is ready, run the following command.
aws lambda-core wait runtime-version-active --runtime-name bash-runtime --name v1If the runtime version's state is
FAILED, the command returns an error. For more information, see If the version fails.
To create a runtime alias
-
To create an alias named
prodthat points to runtime versionv1, run thecreate-runtime-aliascommand.aws lambda-core create-runtime-alias \ --runtime-name bash-runtime \ --name prod \ --runtime-version v1The following example shows an excerpt of the output.
{ "Name": "prod", "Arn": "arn:aws:lambda:us-east-1:123456789012:runtime/bash-runtime/alias/prod", "RuntimeVersion": "v1", "RuntimeVersionArn": "arn:aws:lambda:us-east-1:123456789012:runtime/bash-runtime/version/v1", "State": "CREATING" } -
To wait until the alias is ready, run the following command.
aws lambda-core wait runtime-alias-active --runtime-name bash-runtime --name prod
Step 5: Create and invoke a function
Create a function that uses the Bash runtime. The function's .zip file archive holds only the handler script. The runtime image provides the bootstrap script. For more information, see Using a customer-managed runtime.
To create and invoke a function
-
Create a file named
function.shwith the following content. Thehandlerfunction takes the event data, logs the event data tostderr, and returns a response.function handler () { EVENT_DATA=$1 echo "$EVENT_DATA" 1>&2; RESPONSE="Echoing request: '$EVENT_DATA'" echo $RESPONSE } -
To make the handler script executable and add the script to a .zip file archive, run the following commands.
chmod 755 function.sh zip function.zip function.sh -
To create the function, run the
create-functioncommand. For--role, use the ARN of thebash-tutorial-roleexecution role that you created in Step 1: Create an execution role.aws lambda create-function \ --function-name bash-function \ --runtime custom \ --runtime-config RuntimeArn=${RUNTIME_ARN},RuntimeAlias=prod \ --handler function.handler \ --zip-file fileb://function.zip \ --role arn:aws:iam::${ACCOUNT_ID}:role/bash-tutorial-role \ --architectures x86_64The handler
function.handlertells the Bash runtime to loadfunction.shand call thehandlerfunction. The function must use an architecture that the runtime version supports. The runtime image in this tutorial supports x86_64 only.NoteIf you created the role in the last few seconds, the command might fail with the error
The role defined for the function cannot be assumed by Lambda. Wait about 10 seconds and run the command again. -
To wait until the function is ready to invoke, run the following command.
aws lambda wait function-active-v2 --function-name bash-function -
To invoke the function, run the
invokecommand.aws lambda invoke \ --function-name bash-function \ --payload '{"text":"Hello"}' \ --cli-binary-format raw-in-base64-out \ response.txtThe 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 the following output:
{ "StatusCode": 200, "ExecutedVersion": "$LATEST" } -
To view the function response, display the contents of
response.txt.cat response.txtYou should see the following output:
Echoing request: '{"text":"Hello"}'The response comes from the
handlerfunction, through thebootstrapscript in your customer-managed runtime.
Clean up
Lambda doesn't charge for storing the runtime, its runtime version and alias, or the function. However, Amazon ECR charges for storing the runtime image. When you finish this tutorial, delete the resources that you created. Delete the runtime resources in order: the alias, then the runtime version, then the runtime.
Lambda doesn't delete runtime resources right away. First, Lambda schedules each resource for deletion. You can restore the resource during the waiting period. The following commands use the minimum waiting period of 7 days. For more information, see Deleting and restoring runtimes.
To clean up your resources
-
To delete the function, run the
delete-functioncommand.aws lambda delete-function --function-name bash-function -
To delete the runtime alias, run the
delete-runtime-aliascommand.aws lambda-core delete-runtime-alias \ --runtime-name bash-runtime \ --name prod \ --recovery-window-in-days 7 -
To delete the runtime version, run the
delete-runtime-versioncommand.aws lambda-core delete-runtime-version \ --runtime-name bash-runtime \ --name v1 \ --recovery-window-in-days 7 -
To delete the runtime, run the
delete-runtimecommand.aws lambda-core delete-runtime \ --runtime-name bash-runtime \ --recovery-window-in-days 7You can delete the runtime after the runtime's alias and version are scheduled for deletion.
-
(Optional) To confirm that the runtime is scheduled for deletion, run the
get-runtimecommand.aws lambda-core get-runtime --runtime-name bash-runtime --query StateThe output is
"PENDING_DELETION". -
To delete the Amazon ECR repository and the runtime image, run the
delete-repositorycommand.aws ecr delete-repository --repository-name bash-runtime --forceA restored runtime version needs the original image. If you might restore the runtime version, keep the repository until Lambda permanently deletes the version. For more information, see Container images and charges.
-
To detach the managed policy from the execution role, run the
detach-role-policycommand.aws iam detach-role-policy \ --role-name bash-tutorial-role \ --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole -
To delete the execution role, run the
delete-rolecommand.aws iam delete-role --role-name bash-tutorial-role -
Lambda created a log group named
/aws/lambda/bash-functionin Amazon CloudWatch Logs. To delete the log group, run thedelete-log-groupcommand.Before you run the command, wait at least 1 minute after the last invocation so that Lambda finishes sending log events. Otherwise, Lambda might create the log group again.
aws logs delete-log-group --log-group-name /aws/lambda/bash-function -
(Optional) To remove the runtime image from your computer, run the
docker rmicommand. Thedocker buildcommand stored a copy of the image locally, and deleting the Amazon ECR repository doesn't remove it.docker rmi ${REPO_URI}:v1
Runtimes, runtime versions, and runtime aliases that are scheduled for deletion keep their names and count toward your quotas until Lambda permanently deletes them. To run this tutorial again before then, restore the runtime resources or use different names. For more information, see Restoring a runtime, runtime version, or runtime alias and Customer-managed runtimes in Lambda quotas.
Next steps
To learn more, see the following topics:
-
To roll out a runtime update by pointing an alias to a new runtime version, see Tutorial: Creating and using a customer-managed runtime.
-
To learn what to put in a runtime image, see Building runtime images.
-
To learn about every method that a runtime can call, see Using the Lambda runtime API.