Trying Out a Bash Runtime with the AWS CLI Installed on AWS Lambda Custom Runtimes

Trying Out a Bash Runtime with the AWS CLI Installed on AWS Lambda Custom Runtimes

Steps for building a Docker image, pushing it to ECR, and creating a runtime, version and alias with `aws lambda-core`. Using this runtime, a Lambda function made from a zipped shell script could run the AWS CLI.
2026.11.20

This page has been translated by machine translation. View original

Introduction

On November 18, 2026, AWS Lambda customer-managed runtimes was announced.

https://aws.amazon.com/jp/about-aws/whats-new/2026/11/aws-lambda-customer-managed-runtimes/

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.

https://docs.aws.amazon.com/lambda/latest/dg/runtimes-walkthrough.html

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.

Share this article

AWSのお困り事はクラスメソッドへ