Customer-managed runtimes
A customer-managed runtime is a Lambda runtime that you create and manage as a standalone resource. Lambda Event Functions can use your customer-managed runtime instead of using one of the built-in Lambda-managed runtimes. Customer-managed runtimes aren't available for Lambda Web Functions. You build a runtime once, share it across functions and accounts, and roll out updates to every function that uses it, without redeploying those functions.
Why use customer-managed runtimes
Lambda provides managed runtimes for popular programming languages, automatically handling patches so that you can focus on your code. With these Lambda-managed runtimes, Lambda controls what each runtime contains, when it's updated, and when it's deprecated. In contrast, customer-managed runtimes give you full control over the runtime contents, updates, and lifecycle. You can include any language or language version, your organization's SDKs, security and monitoring tools, and other shared components. Developers using your runtime for their functions keep the .zip file development and automatic runtime updates experience they are familiar with from Lambda-managed runtimes.
Other approaches to customizing the function execution environment carry an operational cost for each function. When using container images or Lambda layers, any changes to shared components require you to redeploy every affected function. In addition, with container images you must rebuild and redeploy your images to apply runtime security patches or other runtime updates. Customer-managed runtimes separate runtime management from function management. The publisher updates the runtime once, and functions pick up the update automatically, without redeployment. You can roll out updates, including security patches, across large numbers of functions, and roll back the same way. For a detailed comparison, see Comparing customer-managed runtimes to other deployment models.
You can also share one runtime across teams, across accounts, or publicly, so that teams standardize on approved components. This central control makes customer-managed runtimes a good fit for the following use cases:
-
Enterprise platform teams – Give every team in your organization a runtime with your approved security and monitoring tools built in, and update those tools centrally.
-
SaaS and PaaS providers – Control the SDKs and libraries that run in your customers' functions, and keep them current.
-
Third-party runtime publishers – Publish runtimes for languages that Lambda doesn't provide a managed runtime for, such as PHP.
-
Control over runtime patching – Take control over runtime patching to meet your organization's change control policy or compliance constraints. Extend the runtime lifetime beyond the published end-of-life schedule.
Previously, Lambda supported 'custom runtimes' by including a runtime in the function's deployment package or in a layer. For clarity, we now call this approach bring your own language (BYOL). Lambda still supports BYOL. However, customer-managed runtimes have significant advantages. They give you full control over the runtime contents, and they decouple runtime management from function management. They also let you manage runtimes at scale across large numbers of functions. For these reasons, we recommend customer-managed runtimes instead of BYOL for most applications.
Runtime publishers and runtime consumers
Customer-managed runtimes split runtime management and function management into two separate roles, the runtime publisher and runtime consumer. For example, a central cloud platform team can publish a runtime, and application teams can consume it for their functions. This creates a clean separation between runtime management and application development. Runtime publishers get control and autonomy over the runtime contents. Runtime consumers can focus on their application, instead of on shared components or runtime customization. One team can also fill both roles, and the roles can span AWS accounts.
As a runtime publisher, you own the runtime resource and its contents, updates, access control, and lifecycle. You're responsible for the following tasks:
-
Runtime contents – The runtime contents typically include the operating system libraries, language runtime, and any shared components. Runtimes also require a runtime interface client (RIC), which acts as the bridge between the Lambda service and the function handler. You define the runtime contents as a container image in Amazon Elastic Container Registry (Amazon ECR). You can start from a Lambda runtime base container image, or build your own runtime image from scratch. For more information, see Creating a runtime.
-
Runtime updates, including security updates – You're responsible for all runtime updates, including security patches for every component in the runtime. If you start from a Lambda base container image, you must rebuild and redeploy your runtime to pick up any updates. You must keep your updates backward compatible with existing functions. For more information, see Building a runtime image from a Lambda base image.
-
Update rollout – You decide when and how updates reach functions. To roll out a new runtime version, you update a runtime alias. By default, Lambda then applies the new runtime version to functions automatically, the same as for functions that use Lambda-managed runtimes. You can choose how to stage the rollout, for example by environment. You monitor the rollout and roll back if needed. For more information, see Runtime aliases, Deploying runtime updates, and Monitoring customer-managed runtimes.
-
Access control – You control who can use the runtime by using a resource-based policy. For more information, see Sharing and controlling access to customer-managed runtimes.
-
Lifecycle and consumer communication – You manage the lifecycle of runtime versions, including deprecation. You also delete runtimes, runtime versions, and runtime aliases that you no longer need. Notifying consumers about updates, deprecations, and deletions is your responsibility. For more information, see Runtime lifecycle and Deleting and restoring runtimes.
As a runtime consumer, you configure your function to use the correct customer-managed runtime and runtime alias, instead of a Lambda-managed runtime identifier such as python3.14. You still deploy your function as a .zip file archive, and you don't see the container images that the runtime publisher uses. Read any guidance from the runtime publisher. For example, check the runtime's description and license information, and use the alias descriptions to choose the right alias. If the publisher defined a deprecation lifecycle, plan your function updates around its dates. Otherwise, your function development experience is the same as with Lambda-managed runtimes. For more information, see Using a customer-managed runtime.
Block dates stop function creates and updates, but they never stop invocations. If the publisher deletes a runtime alias or runtime version that your function depends on, your function enters the Inactive state. Existing execution environments continue to handle invocations, but invocations that require a cold start fail. For more information, see Runtime lifecycle and function states, Runtime lifecycle, and Deleting and restoring runtimes.
A runtime publisher can push updates to the runtime to apply security patches, bug fixes, or other updates. This means they can also push their code into the execution environments of functions that use the runtime. This code runs with the permissions of each function's execution role. Only use customer-managed runtimes from publishers that you trust. For third-party runtimes or critical applications, the publisher might make its runtime images available. If so, you can copy them to your own Amazon ECR repository and create your own customer-managed runtime from them. To control when your function picks up runtime updates, use the Function update or Manual runtime update mode. For more information, see Controlling runtime updates. To detect runtime changes, check the runtime version in the INIT_START log line. For more information, see Check which runtime version your function uses.
Resource model
Customer-managed runtimes use three types of resources: runtimes, runtime versions, and runtime aliases.
-
Runtime – The top-level resource that represents the runtime as a whole, such as a PHP 8 runtime for your organization. The runtime resource is the parent of its runtime versions and runtime aliases. Each runtime has a name, an Amazon Resource Name (ARN), and a description. For more information, see Creating a runtime.
You control access at the runtime level by using a resource-based policy. By default, only the account that owns a runtime can use it. You can share a runtime with specific AWS accounts, with an organization or organizational unit (OU) in AWS Organizations, or publicly. For more information, see Sharing and controlling access to customer-managed runtimes.
-
Runtime version – Represents the contents of the runtime. That is, the file system of the execution environment where Lambda loads and invokes your function code. You package each runtime version as a container image in Amazon ECR.
Runtime versions are immutable. To update a runtime, you create a new runtime version, then migrate functions to that version by updating your runtime aliases. Each runtime version points to a distinct container image. For more information, see Runtime versions.
-
Runtime alias – A named pointer to a runtime version. Functions consume a runtime through an alias. When you update an alias, functions that use it move to the new runtime version at their next cold start, unless you have opted out of automatic runtime updates. Running execution environments keep the previous runtime version until Lambda replaces them, so during a rollout, invocations can run on both versions. For more information, see Runtime aliases, Check which runtime version your function uses, and Monitoring customer-managed runtimes.
Runtimes are Regional resources. You must create a runtime in each AWS Region where you want to use it. For details on how to deploy a runtime across multiple AWS Regions, see Deploying runtimes in multiple Regions.
You manage runtimes, runtime versions, and runtime aliases with the Lambda Core API (aws lambda-core in the AWS CLI). For functions, tags, and resource-based policies, you use the Lambda API (aws lambda).
Comparing customer-managed runtimes to other deployment models
The following table compares customer-managed runtimes with Lambda-managed runtimes, container images, and bring your own language (BYOL). With BYOL, you include the runtime in your function package or in a layer, and use an OS-only runtime.
Like customer-managed runtimes, container images give you full control over the file system of the execution environment. However, with container images, you must rebuild and redeploy each function to apply updates.
| Feature | Lambda-managed runtime | Customer-managed runtime | Container image | BYOL |
|---|---|---|---|---|
| Languages | Only languages that Lambda supports | Any language | Any language | Any language |
| Cross-account sharing | Not applicable | Share the runtime by using a resource-based policy | Share the image across accounts in Amazon ECR | Share the runtime layer across accounts |
| Runtime control | AWS | Runtime publisher | Function developer | Function developer |
| Function deployment format | .zip file | .zip file | Container image | .zip file including language runtime and bootstrap file, or layer |
| Update mechanism | Lambda applies updates automatically | Runtime publisher creates a new runtime version and updates one or more runtime aliases; functions pick up the update at their next cold start | Rebuild the image and redeploy the function | Update the runtime layer and redeploy each function |
| OS patching responsibility | AWS | Runtime publisher | Function developer, by rebuilding from an updated base image | AWS, for the OS-only runtime; function developer for the language runtime or layer |
| Update scale | Lambda-controlled, gradual rollout | Per alias (targeted rollout) | Per function | Per function |
| Deprecation management | AWS | Runtime publisher | Function developer | AWS, for the OS-only runtime; function developer for the language runtime or layer |
Supported features and Regions
Customer-managed runtimes work with Lambda Event Functions only. You can't use a customer-managed runtime with Lambda Web Functions. For information about runtimes for Web Functions, see Lambda Web Function runtimes.
Functions that use customer-managed runtimes can use all Lambda features, with the following exceptions:
-
Lambda SnapStart – Functions that use a customer-managed runtime can't use SnapStart.
-
Lambda@Edge – You can't use functions that use a customer-managed runtime with Lambda@Edge.
Some Lambda features, such as Lambda Managed Instances and response streaming, work only if the runtime implements them. To find out which features a runtime supports, check the runtime publisher's documentation. For information about how runtimes support these features, see Architectures and feature compatibility.
If you're a runtime publisher, note the following limitations:
-
You can't encrypt runtime resources with an AWS KMS customer managed key.
-
You can't use code signing to sign runtime images.
-
You can't publish or update customer-managed runtimes by using the AWS Serverless Application Model (AWS SAM).
If you're a runtime consumer, these publisher limitations don't apply to your functions. Functions that use a customer-managed runtime keep their existing support for AWS KMS customer managed keys and code signing.
For information about defining functions that use customer-managed runtimes with infrastructure as code tools, see Infrastructure as code.
Customer-managed runtimes are available in all commercial AWS Regions.
For quotas, see Customer-managed runtimes in Lambda quotas.
Pricing
There's no additional charge for customer-managed runtimes. Functions that use a customer-managed runtime cost the same as functions that use a Lambda-managed runtime. There's no charge for each runtime version.
Publishers must keep the container image for each runtime version in Amazon ECR for as long as the runtime version exists. Standard Amazon ECR storage pricing applies. For more information, see Amazon ECR pricing
Next steps
To get started with customer-managed runtimes, see the following topics:
-
Runtime publishers: To build a runtime image, see Building runtime images. To create a runtime, see Creating a runtime.
-
Runtime consumers: To configure a function to use a runtime, see Using a customer-managed runtime.
-
For an end-to-end example, see Tutorial: Creating and using a customer-managed runtime.