
Trying Out a Bash Runtime with the AWS CLI Installed on AWS Lambda Custom Runtimes
This page has been translated by machine translation. View original
Introduction
On November 18, 2026, AWS Lambda customer-managed runtimes was announced.
Customer-managed runtimes is a feature that lets you use a runtime you built yourself from a Lambda function. The runtime is created as a resource separate from the function. In the function, instead of an identifier such as python3.14, you specify the runtime's ARN and an alias name.
I built a runtime that lets you write functions as Bash scripts, by adding a Bash bootstrap, the AWS CLI, and jq to the provided:al2023 image.
Test environment
- Region: ap-northeast-1
- Architecture: arm64 (the build host is aarch64)
- Host side: AWS CLI 2.41.1, Docker 29.9.3
- Inside the image: Amazon Linux 2023, aws-cli 2.41.1, jq 1.8.1
Creating the runtime
Defining the image
I use the bootstrap and the ECR repository policy from the following tutorial.
The Dockerfile is the tutorial's Dockerfile with steps added to install unzip, jq, and the AWS CLI. Because the AWS CLI uses the installer for arm64 (zip), unzip is needed to extract it. Save it as Dockerfile.
FROM public.ecr.aws/lambda/provided:al2023
# AWS CLI v2 (official installer zip, latest) and jq
RUN dnf install -y unzip jq \
&& dnf clean all \
&& curl -sS "https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip" -o /tmp/awscliv2.zip \
&& unzip -q /tmp/awscliv2.zip -d /tmp \
&& /tmp/aws/install \
&& rm -rf /tmp/aws /tmp/awscliv2.zip
# 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 bootstrap splits the handler function.handler at the dot, loads function.sh from the first part, and calls the second part as the function name. Save it as bootstrap in the same directory as the Dockerfile.
bootstrap
#!/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"
done
Building and pushing to ECR
Save the repository policy that allows Lambda to read the image as ecr-policy.json.
ecr-policy.json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "LambdaReadAccess",
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": [
"ecr:BatchGetImage",
"ecr:DescribeImages",
"ecr:GetDownloadUrlForLayer"
]
}
]
}
export ACCOUNT_ID=111122223333
export AWS_REGION=ap-northeast-1
export REPO_URI=${ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/devio-bash-runtime-1119
docker build --platform linux/arm64 --tag ${REPO_URI}:v1 .
aws ecr create-repository --repository-name devio-bash-runtime-1119
aws ecr set-repository-policy --repository-name devio-bash-runtime-1119 --policy-text file://ecr-policy.json
aws ecr get-login-password | docker login --username AWS --password-stdin ${ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com
docker push ${REPO_URI}:v1
Runtime, version, and alias
The runtime, version, and alias are created with aws lambda-core. For the version and alias, use wait to wait until they become ACTIVE.
aws lambda-core create-runtime --name devio-bash-1119 --description "Bash runtime with AWS CLI and jq"
aws lambda-core create-runtime-version --runtime-name devio-bash-1119 --name v1 --image-uri ${REPO_URI}:v1
aws lambda-core wait runtime-version-active --runtime-name devio-bash-1119 --name v1
aws lambda-core create-runtime-alias --runtime-name devio-bash-1119 --name prod --runtime-version v1
aws lambda-core wait runtime-alias-active --runtime-name devio-bash-1119 --name prod
The response of aws lambda-core get-runtime-version --runtime-name devio-bash-1119 --name v1 is as follows (excerpt).
{
"Name": "v1",
...
"State": "ACTIVE",
"Platforms": [
{
"Architecture": "arm64",
"Os": "linux",
...
}
],
...
}
Platforms contains one entry for arm64.
Creating and invoking the function
Creating the function
From here on, these are operations on the consumer side that uses the runtime.
Attach only AWSLambdaBasicExecutionRole to the execution role.
Creating the execution role
aws iam create-role --role-name devio-bash-1119-role --assume-role-policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"lambda.amazonaws.com"},"Action":"sts:AssumeRole"}]}'
aws iam attach-role-policy --role-name devio-bash-1119-role --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
Write the function code in function.sh. It outputs the event to stderr, extracts the event's command with jq, and runs it with bash -c. The output is written to stderr and then returned as the function's return value.
function handler () {
EVENT_DATA=$1
echo "$EVENT_DATA" 1>&2
COMMAND=$(echo "$EVENT_DATA" | jq -r '.command')
RESULT=$(bash -c "$COMMAND")
echo "$RESULT" 1>&2
echo "$RESULT"
}
Grant function.sh execute permission and make it into a .zip.
chmod 755 function.sh
zip function.zip function.sh
Specify --runtime custom, pass the runtime's ARN and alias with --runtime-config, and create the function.
aws lambda create-function --function-name devio-bash-1119-fn \
--runtime custom \
--runtime-config RuntimeArn=arn:aws:lambda:${AWS_REGION}:${ACCOUNT_ID}:runtime/devio-bash-1119,RuntimeAlias=prod \
--handler function.handler \
--timeout 30 \
--zip-file fileb://function.zip \
--role arn:aws:iam::${ACCOUNT_ID}:role/devio-bash-1119-role \
--architectures arm64
aws lambda wait function-active-v2 --function-name devio-bash-1119-fn
The response of create-function is as follows (excerpt). From RuntimeVersionConfig, you can see that the function is linked to version v1, which the alias prod points to.
{
...
"Runtime": "custom",
"Handler": "function.handler",
"Timeout": 30,
"MemorySize": 128,
...
"Architectures": [
"arm64"
],
...
"RuntimeVersionConfig": {
"RuntimeVersionArn": "arn:aws:lambda:ap-northeast-1:111122223333:runtime/devio-bash-1119/version/v1"
},
...
"RuntimeConfig": {
"RuntimeArn": "arn:aws:lambda:ap-northeast-1:111122223333:runtime/devio-bash-1119",
"RuntimeAlias": "prod"
}
}
Invocation result
aws lambda invoke --function-name devio-bash-1119-fn --payload '{"command":"aws sts get-caller-identity"}' --cli-binary-format raw-in-base64-out response.json
Pass the command you want to run in command. The content of response.json was as follows.
{
"UserId": "AROAXXXXXXXXXXXXXXXXX:devio-bash-1119-fn",
"Account": "111122223333",
"Arn": "arn:aws:sts::111122223333:assumed-role/devio-bash-1119-role/devio-bash-1119-fn"
}
Arn is the assumed-role of the execution role devio-bash-1119-role. This shows that the execution role's credentials were passed to the aws command inside the function. The execution role's permissions were only AWSLambdaBasicExecutionRole, and aws sts get-caller-identity required no additional permissions. The aws command worked even without setting environment variables such as HOME on the function side.
The logs output to CloudWatch Logs by this invocation are as follows. {"command":"aws sts get-caller-identity"} is the line where echo "$EVENT_DATA" 1>&2 in function.sh output the event passed with --payload. The part from the next { to } (UserId, Account, Arn) is the output of the executed command, written by echo "$RESULT" 1>&2. {"status":"OK"} is the output of the curl with which the bootstrap returns the response, and it is the body returned by the Runtime API.
INIT_START Runtime Version: devio-bash-1119:v1 Runtime Version ARN: arn:aws:lambda:ap-northeast-1:111122223333:runtime/devio-bash-1119/version/v1
START RequestId: 10a0ab8f-80ac-4576-b12f-256de700f193 Version: $LATEST
{"command":"aws sts get-caller-identity"}
{
"UserId": "AROAXXXXXXXXXXXXXXXXX:devio-bash-1119-fn",
"Account": "111122223333",
"Arn": "arn:aws:sts::111122223333:assumed-role/devio-bash-1119-role/devio-bash-1119-fn"
}
{"status":"OK"}
END RequestId: 10a0ab8f-80ac-4576-b12f-256de700f193
REPORT RequestId: 10a0ab8f-80ac-4576-b12f-256de700f193 Duration: 14503.90 ms Billed Duration: 14562 ms Memory Size: 128 MB Max Memory Used: 112 MB Init Duration: 57.30 ms
The INIT_START line is output on every cold start. It shows which runtime version the function ran on.
Execution time by memory
I changed the memory to 128 MB, 512 MB, and 1024 MB, and read Duration from the REPORT line. The measurement used a function that runs aws sts get-caller-identity and filters Account and Arn with jq.
Cold start results:
| Memory | Duration | Init Duration |
|---|---|---|
| 128 MB | 14628.38 ms | 59.51 ms |
| 512 MB | 3328.66 ms | 59.96 ms |
| 1024 MB | 1779.73 ms | 56.00 ms |
Warm start results:
| Memory | Duration |
|---|---|
| 128 MB | 12476.68 ms |
| 512 MB | 3028.41 ms |
| 1024 MB | 1460.02 ms |
Each value is from a single measurement. Max Memory Used was 114 MB for the 128 MB configuration, and 119 MB for the 512 MB and 1024 MB configurations.
Summary
I was able to create a Bash runtime that runs shell scripts using the AWS CLI, by adding a bootstrap, the AWS CLI, and jq to the provided:al2023 image.
On the consumer side, by specifying --runtime custom and --runtime-config, I created a function with a shell script stored in a .zip and ran it on this runtime.
Until now, running a language or version in Lambda that AWS-provided runtimes don't offer required preparing a layer or a Docker image. Please give the newly added customer-managed runtimes a try.
