Skip to content

ql4b/terraform-aws-lambda-shell-runtime-layer

BranchesTags

Repository files navigation

terraform-aws-lambda-shell-runtime-layer

A Terraform module that publishes a Lambda Layer containing a custom runtime for executing shell functions on AWS Lambda with minimal cold-start overhead.

run () {
    curl -Ss https://wttr.in/?format=3
}

That's a complete Lambda function. No SDK, no framework, no build step.

diagram

How it works

A custom AWS Lambda runtime is a program that runs a Lambda function's handler method when the function is invoked.

This module ships pre-built runtime binaries (Go bootstrap) and publishes them as a Lambda Layer. The runtime:

  1. Starts as /var/runtime/bootstrap in the Lambda execution environment
  2. Polls the Lambda Runtime API for invocation events
  3. Sources your handler script (e.g. handler.sh)
  4. Calls the specified function (e.g. run) with the event payload
  5. Returns the function's stdout as the response via the Runtime API

Publishing the runtime as a layer keeps your function deployment packages tiny (just your shell scripts), makes deployments fast, and adds negligible overhead from the layer mount.

Usage

# Publish the runtime layer (once per region)
module "shell_runtime" {
  source = "git::https://github.com/ql4b/terraform-aws-lambda-shell-runtime-layer.git?ref=v1.0.0"

  name         = "shell-runtime"
  architecture = "arm64"
}

# Use it in your functions
module "my_function" {
  source = "git::https://github.com/ql4b/terraform-aws-lambda-function.git?ref=v1.1.0"

  source_dir = "./app"
  name       = "my-function"

  runtime      = "provided.al2023"
  handler      = "handler.run"
  architecture = "arm64"

  layers = [
    module.shell_runtime.layer_arn,
  ]
}

The handler format is <file>.<function> — so handler.run means: source handler.sh, call run().

Multiple functions, one runtime

The layer is published once and shared across functions:

module "shell_runtime" {
  source = "git::https://github.com/ql4b/terraform-aws-lambda-shell-runtime-layer.git?ref=v1.0.0"

  name         = "shell-runtime"
  architecture = "arm64"
}

module "function_a" {
  source = "git::https://github.com/ql4b/terraform-aws-lambda-function.git?ref=v1.1.0"

  source_dir   = "./app"
  name         = "function-a"
  runtime      = "provided.al2023"
  handler      = "handler.a"
  architecture = "arm64"
  layers       = [module.shell_runtime.layer_arn]
}

module "function_b" {
  source = "git::https://github.com/ql4b/terraform-aws-lambda-function.git?ref=v1.1.0"

  source_dir   = "./app"
  name         = "function-b"
  runtime      = "provided.al2023"
  handler      = "handler.b"
  architecture = "arm64"
  layers       = [module.shell_runtime.layer_arn]
}

Examples

See examples/ for working deployments:

Example Description
basic Minimal function with runtime layer only
endpoints Function URLs (public + private)
aws-services Functions calling S3, SNS, SSM, SQS, DynamoDB
complete Multiple functions with different layer combinations 
cd examples/basic
terraform init
terraform apply

The basic example deploys a function with handler handler.run that calls curl:

#!/bin/bash

set -euo pipefail

run () {
    curl -Ss https://wttr.in/?format=3
}

Note: curl is available in provided.al2023. For jq or other tools, add them as a separate layer.

What's available in the execution environment

With provided.al2023, your functions run on a minimal Amazon Linux 2023 environment. This gives you a base set of utilities out of the box — no layers needed:

  • curl (with --aws-sigv4 support)
  • bash, sh
  • cat, grep, sed, awk, cut, sort, head, tail
  • date, env, mktemp, base64

This is the custom runtime contract: AWS provides the OS and the Runtime API, you provide the bootstrap and your handler. The runtime layer handles the bootstrap, so your function packages contain only shell scripts.

For anything beyond what the OS ships — JSON processing, HTML parsing, UUID generation — you add tool layers.

Adding Tool Layers

The runtime layer provides the shell bootstrap. To add CLI tools (jq, htmlq, uuid, etc.), compose additional layers from lambda-shell-layers:

module "shell_runtime" {
  source = "git::https://github.com/ql4b/terraform-aws-lambda-shell-runtime-layer.git?ref=v1.0.0"

  name         = "shell-runtime"
  architecture = "arm64"
}

module "jq" {
  source = "git::https://github.com/ql4b/terraform-aws-lambda-layer.git?ref=v1.2.0"

  name       = "jq"
  source_url = "https://github.com/ql4b/lambda-shell-layers/releases/download/v0.0.3/jq-arm64-layer.zip"

  compatible_architectures = ["arm64"]
  enable_ssm_parameters    = false
}

module "my_function" {
  source = "git::https://github.com/ql4b/terraform-aws-lambda-function.git?ref=v1.1.0"

  source_dir   = "./app"
  name         = "my-function"
  runtime      = "provided.al2023"
  handler      = "handler.run"
  architecture = "arm64"

  layers = [
    module.shell_runtime.layer_arn,
    module.jq.layer_arn,
  ]
}

Each function gets only the layers it needs — keeping deployment packages small and cold starts fast.

See examples/complete/ for a full example with multiple functions and layer combinations.

Calling AWS Services without SDK

See examples/aws-services/ — interact with S3, DynamoDB, SNS, SSM, and SQS directly from shell using curl --aws-sigv4. No AWS CLI or SDK required, just the built-in curl from provided.al2023.

HTTP Endpoints

See examples/endpoints/ — expose shell functions as HTTP endpoints via Lambda Function URLs (public or IAM-authenticated), custom domains with CloudFront, or API Gateway with usage plans.

Architecture

The module ships pre-built runtime binaries for both architectures:

runtime/
├── bootstrap-arm64.zip    # Graviton (arm64) — recommended
├── bootstrap-amd64.zip    # Intel (x86_64)
├── main.go                # Runtime source code
├── go.mod
└── Makefile               # Build targets

The runtime source is available in runtime/ — a minimal Go program that implements the Lambda Runtime API loop and shells out to your handler function.

arm64 is recommended — it's 20% cheaper and generally faster on Lambda (Graviton2/3).

Cold Start Performance

All values in milliseconds. Measured on provided.al2023 with 128MB memory.

arm64 — runtime only (examples/aws-services)

Function Layers median p90 p99 iqr n
buckets 1 (runtime) 21.56 22.53 23.68 3.27 59
publish 1 (runtime) 19.54 22.05 22.08 2.24 10
get-param 2 (runtime + jq) 18.96 22.20 22.51 3.57 9
send-message 2 (runtime + jq) 19.34 21.90 22.75 0.63 12
put-item 3 (runtime + jq + uuid) 21.49 22.34 22.43 2.48 9

arm64 — with Function URLs (examples/endpoints)

Function Layers median p90 p99 iqr n
public 2 (runtime + jq) 19.05 22.29 22.58 2.71 24
private 2 (runtime + jq) 19.24 22.04 22.44 1.79 16

arm64 — multiple tool layers (examples/complete)

Function Layers median p90 p99 iqr n
weather 2 (runtime + jq) 19.06 22.32 27.56 3.00 53
events 2 (runtime + jq) 19.15 22.18 22.50 3.04 59
id 3 (runtime + jq + uuid) 19.29 22.12 22.77 2.82 18
runtimes 3 (runtime + jq + htmlq) 19.20 22.30 23.29 3.34 60
status 3 (runtime + jq + http-cli) 19.98 22.26 22.79 2.82 32

x86_64 — multiple tool layers (examples/complete)

Function Layers median p90 p99 iqr n
weather 1 (runtime) 25.71 26.67 28.10 0.46 43
events 2 (runtime + jq) 25.56 26.14 26.52 0.66 60
id 3 (runtime + jq + uuid) 25.65 26.20 32.12 0.57 24
runtimes 3 (runtime + jq + htmlq) 25.70 26.47 28.14 0.97 60
status 3 (runtime + jq + http-cli) 25.54 26.50 28.79 0.93 28

Key observations

  • arm64 is ~25% faster than x86_64 on cold start (~19ms vs ~25ms median)
  • Layer count has negligible impact — 1 layer vs 3 layers shows no meaningful difference
  • Handler complexity is irrelevant — init only sources the file, doesn't execute the function
  • IQR < 4ms across all configurations — cold starts are highly predictable

Benchmark methodology

Cold starts are measured by forcing fresh execution environments (lambda-benchmarks):

  1. Update the function configuration (environment variable change) to invalidate all warm environments
  2. Wait for propagation
  3. Invoke 120 times concurrently (parallel -j 60) — Lambda provisions new environments for each concurrent request
  4. Wait for CloudWatch logs to flush
  5. Extract Init Duration from REPORT lines and compute stats with datamash

This produces real cold starts without artificial function updates between each invocation, giving a realistic distribution from a single burst.

Requirements

Name Version
terraform ~> 1.3
aws ~> 6.0

Providers

No providers.

Modules

Name Source Version
runtime git::https://github.com/ql4b/terraform-aws-lambda-layer.git v1.1.0
this cloudposse/label/null 0.25.0

Resources

No resources.

Inputs

Name Description Type Default Required
additional_tag_map Additional key-value pairs to add to each map in tags_as_list_of_maps. Not added to tags or id.
This is for some rare cases where resources want additional configuration of tags
and therefore take a list of maps with tag key, value, and additional configuration.		 map(string) {} no
architecture architecture the lambda layer is compatible with string "arm64" no
attributes ID element. Additional attributes (e.g. workers or cluster) to add to id,
in the order they appear in the list. New attributes are appended to the
end of the list. The elements of the list are joined by the delimiter
and treated as a single ID element.		 list(string) [] no
context Single object for setting entire context at once.
See description of individual variables for details.
Leave string and numeric variables as null to use default value.
Individual variable settings (non-null) override settings in context object,
except for attributes, tags, and additional_tag_map, which are merged.		 any 
{
  "additional_tag_map": {},
  "attributes": [],
  "delimiter": null,
  "descriptor_formats": {},
  "enabled": true,
  "environment": null,
  "id_length_limit": null,
  "label_key_case": null,
  "label_order": [],
  "label_value_case": null,
  "labels_as_tags": [
    "unset"
  ],
  "name": null,
  "namespace": null,
  "regex_replace_chars": null,
  "stage": null,
  "tags": {},
  "tenant": null
}
 no
delimiter Delimiter to be used between ID elements.
Defaults to - (hyphen). Set to "" to use no delimiter at all.		 string null no
descriptor_formats Describe additional descriptors to be output in the descriptors output map.
Map of maps. Keys are names of descriptors. Values are maps of the form
{<br/> format = string<br/> labels = list(string)<br/>}
(Type is any so the map values can later be enhanced to provide additional options.)
format is a Terraform format string to be passed to the format() function.
labels is a list of labels, in order, to pass to format() function.
Label values will be normalized before being passed to format() so they will be
identical to how they appear in id.
Default is {} (descriptors output will be empty).		 any {} no
enabled Set to false to prevent the module from creating any resources bool null no
environment ID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT' string null no
id_length_limit Limit id to this many characters (minimum 6).
Set to 0 for unlimited length.
Set to null for keep the existing setting, which defaults to 0.
Does not affect id_full.		 number null no
label_key_case Controls the letter case of the tags keys (label names) for tags generated by this module.
Does not affect keys of tags passed in via the tags input.
Possible values: lower, title, upper.
Default value: title.		 string null no
label_order The order in which the labels (ID elements) appear in the id.
Defaults to ["namespace", "environment", "stage", "name", "attributes"].
You can omit any of the 6 labels ("tenant" is the 6th), but at least one must be present.		 list(string) null no
label_value_case Controls the letter case of ID elements (labels) as included in id,
set as tag values, and output by this module individually.
Does not affect values of tags passed in via the tags input.
Possible values: lower, title, upper and none (no transformation).
Set this to title and set delimiter to "" to yield Pascal Case IDs.
Default value: lower.		 string null no
labels_as_tags Set of labels (ID elements) to include as tags in the tags output.
Default is to include all labels.
Tags with empty values will not be included in the tags output.
Set to [] to suppress all generated tags.
Notes:
The value of the name tag, if included, will be the id, not the name.
Unlike other null-label inputs, the initial setting of labels_as_tags cannot be
changed in later chained modules. Attempts to change it will be silently ignored.		 set(string) 
[
  "default"
]
 no
name ID element. Usually the component or solution name, e.g. 'app' or 'jenkins'.
This is the only ID element not also included as a tag.
The "name" tag is set to the full id string. There is no tag with the value of the name input.		 string null no
namespace ID element. Usually an abbreviation of your organization name, e.g. 'eg' or 'cp', to help ensure generated IDs are globally unique string null no
regex_replace_chars Terraform regular expression (regex) string.
Characters matching the regex will be removed from the ID elements.
If not set, "/[^a-zA-Z0-9-]/" is used to remove all characters other than hyphens, letters and digits.		 string null no
stage ID element. Usually used to indicate role, e.g. 'prod', 'staging', 'source', 'build', 'test', 'deploy', 'release' string null no
tags Additional tags (e.g. {'BusinessUnit': 'XYZ'}).
Neither the tag keys nor the tag values will be modified by this module.		 map(string) {} no
tenant ID element _(Rarely used, not included by default)_. A customer identifier, indicating who this instance of a resource is for string null no

Outputs

Name Description
layer_arn Lambda layer ARN
layer_version Lambda layer version

About

Terraform module that publishes a shell runtime layer for AWS Lambda

Topics

terraform-module lambda-custom-runtime lambda-shell-runtime lambda-shell-runtime-layer

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v1.0.0 Latest
Jun 11, 2026

Packages

 
 
 

Contributors

Languages