Building runtime images
Each version of a customer-managed runtime references a container image in Amazon Elastic Container Registry (Amazon ECR) to define the runtime file system contents. The image has everything that Lambda needs to run function code in your language. This topic explains what goes into an image, how Lambda uses it, and how to structure it.
Ways to build a runtime image
You can build a runtime image in one of the following ways:
-
Start from a Lambda base image – Add your components on top of an image that already has the operating system (OS), language runtime, and runtime interface client (RIC). Each language base image has the same components as the Lambda-managed runtime for that language. For more information, see Building a runtime image from a Lambda base image.
-
Build from scratch with a Lambda runtime interface client – Start from a base image without a language runtime. Then add a language runtime and one of the open-source RICs from Lambda. For a list of these RICs, see Open-source repositories. For more information, see Building runtime images from scratch.
-
Support a new language with your own RIC – Start from a base image without a language runtime, and write your own RIC for a language that Lambda doesn't support. Your RIC uses the Lambda runtime API to get events and send responses. For more information, see Supporting a new programming language for AWS Lambda Event Functions and Using the Lambda runtime API.
For the second and third options, you can start from either a Lambda OS-only base imagepublic.ecr.aws/lambda/provided:al2023 or a base image of your choice. The Lambda OS-only base images are updated regularly with the latest security patches. For more information, see OS-only runtimes.
The following table compares the three approaches.
| Approach | Effort | Control | Patching | Typical use |
|---|---|---|---|---|
| Start from a Lambda base image | Low. Lambda provides the OS, language runtime, and RIC. | You control what you add. Lambda controls the base. | Lambda patches the base image. You rebuild to get the patches, and you patch what you add. | Add your own libraries, certificates, or extensions to a language that Lambda supports. |
| Build from scratch with a Lambda RIC | Medium. You assemble the runtime from the base image, adding the language runtime and one of the Lambda open-source RICs. | You control the language runtime and choice of RIC. The base image (Lambda or other) controls the OS libraries. | You patch the language runtime and OS libraries, and keep the RIC up to date. If you use a Lambda OS-only base image, rebuild to get OS patches. | Use a different OS or language version, or meet strict security rules. |
| Support a new language with your own RIC | High. You assemble the runtime from the base image, adding the language runtime and your own RIC, which you write and maintain. | You control the language runtime, your RIC, and how the runtime communicates with Lambda. The base image (Lambda or other) controls the OS libraries. | You patch the language runtime, your RIC, and OS libraries. If you use a Lambda OS-only base image, rebuild to get OS patches. | Run a language or framework that Lambda doesn't support. |
What goes into a runtime image
A runtime image holds everything that functions need to run, except function code and layers. It typically includes the following:
-
OS libraries – The system libraries and packages that the language runtime and function code need.
-
Language runtime – The interpreter or virtual machine for your language, if it needs one. For example, Node.js, Python, or Java.
-
Runtime interface client – The code that loads the function handler. It gets events from Lambda and sends back responses.
-
Bootstrap – The file that Lambda runs to start the runtime. This is the entrypoint of the container image.
-
Packages and certificates – Extra packages, and the trusted certificates that code uses for secure connections.
-
Shared components – Items that you want every function to have, such as your own SDKs, security tools, and extensions.
A runtime image also needs environment variables, such as PATH. Lambda base images, including the OS-only base image, already set them. Lambda sets variables such as LAMBDA_TASK_ROOT when it starts the runtime. If you use your own base image, see Setting environment variables in the runtime image.
Don't put secrets in a runtime image. Function code can read everything in the image. Anyone who can deploy or invoke a function that uses the runtime can read the entire runtime contents. Don't include passwords, keys, tokens, or sensitive settings.
Choose the packages that you include in a runtime image carefully. For each package, check the following:
-
Backward compatibility policy – Functions that use the runtime pick up runtime updates automatically. Future updates to each package must stay backward compatible with existing function code. Consider both API compatibility and ABI compatibility. API compatibility covers the source-level interfaces that function code calls. ABI compatibility covers binary interfaces, for example for native extensions or compiled dependencies.
-
Support period – Check how long each package is supported, or the package's end-of-life policy. A package's end of support can determine when you need to deprecate the runtime.
File system layout
Lambda uses some directories for function code, layers, and temporary storage. Put your runtime files only in the runtime directories. The following table describes each directory.
| Directory | Purpose | Guidance for runtime images |
|---|---|---|
/var/runtime |
The runtime code and libraries. In Lambda base images, this directory includes the bootstrap. | We recommend that you put the bootstrap here. If you put the bootstrap somewhere else, point the image's ENTRYPOINT to it. We also recommend that you put the code libraries that you add here. In a runtime image that you build from a Lambda base image, use the language runtime's default library location instead. For more information, see Adding your components. |
/var/runtime-opt/extensions |
Runtime-level extensions that you manage as the runtime publisher. | Put extensions that every function needs here. For more information, see Adding code libraries and extensions. |
/opt |
Reserved for function layers. | Don't put anything in /opt. |
/var/task |
Reserved for function code from the .zip file archive. | Required. Create /var/task, but leave it empty. Lambda mounts the function code there. For more information, see Required paths. |
/tmp |
Writable temporary storage for the function. | Don't put anything in /tmp. |
At run time, the file system is read-only, except for /tmp. This behavior is the same as for other Lambda Event Functions. Make sure that your runtime doesn't write to other directories.
Required paths
Every runtime image must contain the following paths. Lambda mounts over these paths when it creates the execution environment.
-
/etc/hosts– A file. The file can be empty. Lambda adds its own entries. If the file is empty, the execution environment has no entry forlocalhost. We recommend that you keep the default/etc/hostsfile from your base distribution. -
/etc/resolv.conf– A file. The file can be empty. Lambda provides the DNS configuration. -
/var/task– A directory. Leave the directory empty. Lambda mounts the function code there.
Lambda base images include all three paths. If you build from another base image, such as Alpine Linux, make sure that the image contains them.
Some base images don't include /etc/hosts or /etc/resolv.conf in the image itself. Docker adds these files only when a container runs. As a result, a file that you create with a RUN instruction doesn't persist in the image. Instead, use a COPY instruction to add each file to the image. The following Dockerfile instructions add the required paths. In this example, hosts and resolv.conf are files in the build context.
COPY hosts /etc/hosts COPY resolv.conf /etc/resolv.conf RUN mkdir -p /var/task
How Lambda starts your runtime
Every runtime image must work with the way that Lambda starts the runtime. When Lambda sets up an execution environment for a function, Lambda runs the executable that the image's ENTRYPOINT specifies. Lambda passes the function's handler to the executable as the last argument. The handler is the Handler property in the function configuration. If the image doesn't set an ENTRYPOINT, Lambda runs /var/runtime/bootstrap. Lambda places the function code in /var/task. Use the exec form of ENTRYPOINT, which is a JSON array, so that Lambda can pass the handler to your runtime.
Customer-managed runtimes don't use the image's CMD. This behavior is different from container image functions. When you package a function as a container image, you set the handler in the image. In a Lambda base image, you set the handler with CMD, and Docker passes the CMD value to the ENTRYPOINT. For more information, see Create a Lambda Event Function using a container image.
When you build a runtime image, don't include the handler in ENTRYPOINT or CMD. Functions that use your runtime are .zip file archive functions. Lambda supplies the handler from the function configuration as the last argument passed to the ENTRYPOINT.
Lambda base images set up the runtime startup for you. For more information, see How Lambda base images start the runtime. If you build a runtime image from scratch, see The runtime startup contract.
Lambda base images also set the environment variables that Lambda runtimes need. If you build a runtime image from scratch, see Setting environment variables in the runtime image.
Adding code libraries and extensions
You can add libraries and extensions to your runtime. Every function that uses the runtime then gets them. For example, you can add your own SDK or a monitoring agent.
-
Code libraries – We recommend that you put code libraries in
/var/runtime. In a runtime image that you build from a Lambda base image, put them in the language runtime's default library location instead, such assite-packagesfor Python. For more information, see Adding your components. Resolve conflicts with the runtime's own libraries when you build the image. -
Extensions – Put runtime-level extensions in
/var/runtime-opt/extensions. Lambda starts each file in this directory, just as it does for/opt/extensions. Each extension must register with the Lambda Extensions API. For more information, see Using the Lambda Extensions API to create extensions.
Extensions in /opt/extensions run alongside your runtime's extensions. Functions and layers can override the extensions in your runtime. If /opt/extensions and /var/runtime-opt/extensions both have a file with the same name, only the file in /opt/extensions runs, and Lambda logs a warning. Because a function can replace a runtime extension in this way, don't rely on a runtime extension to enforce a control that functions must not bypass.
You can't attach Lambda layers to a runtime. Add everything that the runtime needs to the image when you build it. Function developers can still add layers to their functions. For more information about layers, see Managing Lambda Event Function dependencies with layers.
Architectures and feature compatibility
Some runtime features, such as support for the x86_64 and arm64 architectures and Lambda Managed Instances, require support in the runtime. Lambda blocks functions from using features that their runtime doesn't support.
Lambda reads the supported architectures and features of a runtime version from its container image. You can't set them when you create a runtime version.
The architectures and features are mirrored from the runtime version to any runtime alias that references the version. To prevent regressions for existing functions, you can't update an alias to reference a runtime version that removes an architecture or feature. For more information, see Runtime version compatibility and Alias compatibility.
Lambda tracks some features as capabilities on each runtime version and alias, and checks them when a consumer creates or updates a function. Lambda handles other features at a different time, or not at all. The following table summarizes how Lambda handles each feature.
| Feature | Tracked as a capability? | How you set it | Notes |
|---|---|---|---|
| Integration model | Yes | Add a label to the image. | Optional. Declares how the runtime connects to Lambda. If the image doesn't set the label, Lambda uses RuntimeAPI. For more information, see Feature compatibility labels. |
| Architectures | Yes | Determined by the image platforms. | A function can use the runtime only if the runtime supports the function's architecture. For more information, see Architectures. |
| Lambda Managed Instances | Yes | Add a label to the image. | Declares whether functions on Lambda Managed Instances can use the runtime. If the image doesn't set the label to Supported, functions on Lambda Managed Instances can't use the runtime. For more information, see Lambda Managed Instances. |
| Response streaming | No | Implement it in the runtime. | Lambda doesn't track or enforce response streaming. A runtime that supports it must implement the streaming response mode of the Lambda runtime API. For more information, see Implementing response streaming in your runtime and Response streaming for Lambda Event Functions. |
| Durable functions | No | No runtime changes needed. | The function needs the appropriate SDK and configuration. |
| Bundled SDKs | No | No runtime changes needed. | A runtime can package an SDK. Describe the SDK in the runtime or alias description. |
Lambda checks architecture and Lambda Managed Instances compatibility when a consumer creates or updates a function, or pins it to a runtime version in Manual mode.
Lambda also checks that a runtime version supports at least the capabilities of any alias that points to the version. For more information, see How Lambda checks alias compatibility.
Architectures
Lambda determines the architectures that a runtime supports from the platforms in the container image. There's no label for architectures. You can build a runtime image for one architecture, or for both:
-
Single-architecture image – An image for either
x86_64orarm64. The runtime version supports only that architecture. -
Multi-architecture image – An image index (manifest list) with an image for each architecture. The runtime version supports both architectures.
A function can use a runtime only if the runtime supports the function's architecture. When a function uses a multi-architecture runtime version, Lambda selects the image that matches the function's architecture. For more information about how Lambda reads architectures from an image, see Supported architectures. For more information about function architectures, see Selecting and configuring an instruction set architecture for your Lambda function.
To build a multi-architecture image, use the docker buildx build command and specify both platforms:
docker buildx build \ --platform linux/amd64,linux/arm64 \ --tag 123456789012.dkr.ecr.us-east-1.amazonaws.com/companyphp8:v8.3.1 \ --push .
A multi-architecture runtime version must support the same features for both architectures. To offer different features for each architecture, publish single-architecture versions and point a separate alias to each one, or create separate runtimes.
Feature compatibility labels
To declare which features your runtime supports, add Docker LABEL instructions to the image's Dockerfile. Lambda reads the labels when you publish a runtime version, and sets the version's capabilities from them. An alias reflects the capabilities of the version that the alias points to. For more information, see Runtime version compatibility and Alias compatibility.
Keep the following in mind when you set labels:
-
Labels are inherited from base images. Lambda base images set the integration model and Lambda Managed Instances labels, so an image that you build from a Lambda base image inherits them. You can override an inherited label with your own
LABELinstruction. -
Label values aren't case-sensitive.
-
In a multi-architecture image, labels are stored in each architecture's image, not in the image index (manifest list). The images for both
x86_64andarm64must therefore have the same labels. When you build both platforms with one docker buildx build command, as shown in Architectures, both images get the same labels from the same Dockerfile. If you build the images separately and combine them into an image index, for example with docker buildx imagetools create, make sure that each image has the same labels.
Integration model
The integration model declares how the runtime connects to Lambda. The only supported value is RuntimeAPI, which means that the runtime uses the Lambda runtime API and can be used with Lambda Event Functions. For more information, see Using the Lambda runtime API.
If the image doesn't set this label, Lambda uses RuntimeAPI. For runtimes that Lambda Event Functions use, you don't need to set the label. To set it explicitly, add the following LABEL instruction:
LABEL com.amazonaws.lambda.feature.integrationmodel="RuntimeAPI"
Lambda Managed Instances
This label declares whether functions on Lambda Managed Instances can use the runtime. To support Lambda Managed Instances, your runtime must also handle multiple invocations at the same time in one execution environment. For more information, see Supporting a new programming language for AWS Lambda Event Functions.
Before you set this label, make sure that your runtime meets the requirements in Supporting Lambda Managed Instances in your runtime. Functions on Lambda Managed Instances also need the Lambda service principal to have the ecr:DescribeImages permission on your repository. For more information, see Grant Lambda access to your Amazon ECR repository.
Set the label to one of the following values:
-
Supported– Functions on Lambda Managed Instances can use the runtime. -
NotSupported– Functions on Lambda Managed Instances can't use the runtime.
LABEL com.amazonaws.lambda.feature.managedinstances="Supported"
To support Lambda Managed Instances, set the label to Supported. The value isn't case-sensitive, so supported also works. Lambda treats any other value as NotSupported. If the image doesn't set this label, the runtime version doesn't support Lambda Managed Instances. Functions on Lambda Managed Instances can't use the runtime version.
Combined example
The following Dockerfile sets the Lambda Managed Instances label on a runtime image that builds from a Lambda base image. The image doesn't set the integration model label, so Lambda uses RuntimeAPI.
FROM public.ecr.aws/lambda/python:3.14 LABEL com.amazonaws.lambda.feature.managedinstances="Supported"
You can also set several labels in a single LABEL instruction. The following example also sets the integration model explicitly:
LABEL com.amazonaws.lambda.feature.integrationmodel="RuntimeAPI" \ com.amazonaws.lambda.feature.managedinstances="Supported"
Image requirements and best practices
Follow these requirements and best practices when you build and store runtime images.
Do the following:
-
Include the required paths – Make sure that the image contains the
/etc/hostsand/etc/resolv.conffiles and the/var/taskdirectory. Lambda base images include them. For more information, see Required paths. -
Stay within the size limit – For the maximum size of a runtime image, see Customer-managed runtimes in Lambda quotas.
-
Keep images small – Include only what functions need. Smaller images help reduce cold start times. Lambda caches runtime images that many functions share, so speed improves with use.
-
Store images in the same AWS Region – Push the image to an Amazon ECR repository in the same Region as the runtime. The repository can be in a different AWS account. To use the runtime in other Regions, replicate the image to each Region. For more information, see Deploying runtimes in multiple Regions.
-
Keep images while runtime versions exist – You must keep the image in Amazon ECR for as long as any runtime version uses the image. If you delete the image, functions that use a runtime version based on the image become
Inactive. This change can take up to 24 hours. Existing execution environments continue to handle invocations, but invocations that require a cold start fail. Deleting the repository or removing Lambda's access to the image has the same effect. The functions recover automatically after you restore the image. A runtime version refers to the image by digest (ResolvedUri), so the restored image must have an identical digest. Standard Amazon ECR storage rates apply. For more information, see Runtime versions. -
Use unique tags or digests – Give each build a unique tag, or refer to images by digest. When you create a runtime version, Lambda resolves the tag to a digest. Retagging an image later doesn't change the runtime version.
-
Patch regularly – You're responsible for patching every part of the image. Rebuild it often to include security fixes, and publish a new runtime version. If you use a Lambda base image, rebuild to get its updates. For more information, see Deploying runtime updates.
-
Test images locally – Test your runtime with sample functions before you publish a runtime version.
-
Document your runtime – Tell your runtime consumers the handler format, what the runtime includes, what it supports, and which runtime aliases they can use.
Don't do the following:
-
Don't include secrets – Don't put passwords, keys, tokens, or other sensitive settings in a runtime image, including in environment variables. For more information, see What goes into a runtime image.
-
Don't use reserved directories – Don't put anything in
/optor/var/task. Lambda uses these directories for layers and function code. The image must still contain the/var/taskdirectory, so create it, but leave it empty. -
Don't rely on retagging – Moving a tag to a new image doesn't change a runtime version. To update a runtime, publish a new runtime version and update your runtime aliases.
-
Don't delete images that runtime versions use – Delete an image only after Lambda permanently deletes every runtime version that uses the image. A runtime version that is scheduled for deletion still needs the image, so that you can restore the version. For more information, see Container images and charges.
Next steps
To build your runtime image, see the following topics:
-
To start from a Lambda base image, see Building a runtime image from a Lambda base image.
-
To build from scratch with a Lambda runtime interface client, see Building runtime images from scratch.
-
To support a new language with your own runtime interface client, see Supporting a new programming language for AWS Lambda Event Functions.
After you build and push your image, continue with the following topics:
-
To create a runtime, see Creating a runtime.
-
To publish your image as a runtime version, see Runtime versions.
-
For an overview of customer-managed runtimes, see Customer-managed runtimes.