Lambda runtime updates - Amazon Lambda
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Lambda runtime updates

Lambda keeps each managed runtime up to date with security updates, bug fixes, new features, performance enhancements, and support for minor version releases. These runtime updates are published as runtime versions. Lambda applies runtime updates to functions by migrating the function from an earlier runtime version to a new runtime version.

By default, for functions using managed runtimes, Lambda applies runtime updates automatically. With automatic runtime updates, Lambda takes on the operational burden of patching the runtime versions. For most customers, automatic updates are the right choice. For more information, see Runtime management controls.

Lambda also publishes each new runtime version as a container image. To update runtime versions for container-based functions, you must create a new container image from the updated base image and redeploy your function.

Each runtime version is associated with a version number and an ARN (Amazon Resource Name). Runtime version numbers use a numbering scheme that Lambda defines, independent of the version numbers that the programming language uses. The runtime version ARN is a unique identifier for each runtime version.

You can view the ARN of your function's current runtime version in the INIT_START line of your function logs and in the Lambda console.

Runtime versions should not be confused with runtime identifiers. Each runtime has a unique runtime identifier, such as python3.9 or nodejs18.x. These correspond to each major programming language release. Runtime versions describe the patch version of an individual runtime.

Note

The ARN for the same runtime version number can vary between Amazon Web Services Regions and CPU architectures.

Runtime management controls

Lambda strives to provide runtime updates that are backward compatible with existing functions. However, as with software patching, there are rare cases in which a runtime update can negatively impact an existing function. For example, security patches can expose an underlying issue with an existing function that depends on the previous, insecure behavior. Lambda runtime management controls help reduce the risk of impact to your workloads in the rare event of a runtime version incompatibility. For each function version ($LATEST or published version), you can choose one of the following runtime update modes:

  • Auto (default) – Automatically update to the most recent and secure runtime version using Two-phase runtime version rollout. We recommend this mode for most customers so that you always benefit from runtime updates.

  • Function update – Update to the most recent and secure runtime version when you update your function. When you update your function, Lambda updates the runtime of your function to the most recent and secure runtime version. This approach synchronizes runtime updates with function deployments, giving you control over when Lambda applies runtime updates. With this mode, you can detect and mitigate rare runtime update incompatibilities early. When using this mode, you must regularly update your functions to keep their runtime up to date.

  • Manual – Manually update your runtime version. You specify a runtime version in your function configuration. The function uses this runtime version indefinitely. In the rare case in which a new runtime version is incompatible with an existing function, you can use this mode to roll back your function to an earlier runtime version. We recommend against using Manual mode to try to achieve runtime consistency across deployments. For more information, see Roll back a runtime version.

Responsibility for applying runtime updates to your functions varies according to which runtime update mode you choose. For more information, see Shared responsibility model.

Two-phase runtime version rollout

Lambda introduces new runtime versions in the following order:

  1. In the first phase, Lambda applies the new runtime version whenever you create or update a function. A function gets updated when you call the UpdateFunctionCode or UpdateFunctionConfiguration API operations.

  2. In the second phase, Lambda updates any function that uses the Auto runtime update mode and that hasn't already been updated to the new runtime version.

The overall duration of the rollout process varies according to multiple factors, including the severity of any security patches included in the runtime update.

If you're actively developing and deploying your functions, you will most likely pick up new runtime versions during the first phase. This synchronizes runtime updates with function updates. In the rare event that the latest runtime version negatively impacts your application, this approach lets you take prompt corrective action. Functions that aren't in active development still receive the operational benefit of automatic runtime updates during the second phase.

This approach doesn't affect functions set to Function update or Manual mode. Functions using Function update mode receive the latest runtime updates only when you create or update them. Functions using Manual mode don't receive runtime updates.

Lambda publishes new runtime versions in a gradual, rolling fashion across Amazon Web Services Regions. If your functions are set to Auto or Function update modes, it's possible that functions deployed at the same time to different Regions, or at different times in the same Region, will pick up different runtime versions. Customers who require guaranteed runtime version consistency across their environments should use container images to deploy their Lambda functions. The Manual mode is designed as a temporary mitigation to enable runtime version rollback in the rare event that a runtime version is incompatible with your function.

Roll back a runtime version

In the rare event that a new runtime version is incompatible with your existing function, you can roll back its runtime version to an earlier one. This keeps your application working and minimizes disruption, providing time to remedy the incompatibility before returning to the latest runtime version.

Lambda doesn't impose a time limit on how long you can use any particular runtime version. However, we strongly recommend updating to the latest runtime version as soon as possible to benefit from the latest security patches, performance improvements, and features. Lambda provides the option to roll back to an earlier runtime version only as a temporary mitigation in the rare event of a runtime update compatibility issue. Functions using an earlier runtime version for an extended period may eventually experience degraded performance or issues, such as a certificate expiry, which can cause them to stop working properly.

You can roll back a runtime version in the following ways:

For more information, see Introducing Amazon Lambda runtime management controls on the Amazon Compute Blog.

Roll back a runtime version using Manual runtime update mode

If you're using the Auto runtime version update mode, or you're using the $LATEST runtime version, you can roll back your runtime version using the Manual mode. For the function version you want to roll back, change the runtime version update mode to Manual and specify the ARN of the previous runtime version. For more information about finding the ARN of the previous runtime version, see Identifying runtime version changes.

Note

If the $LATEST version of your function is configured to use Manual mode, then you can't change the CPU architecture or runtime version that your function uses. To make these changes, you must change to Auto or Function update mode.

Roll back a runtime version using published function versions

Published function versions are an immutable snapshot of the $LATEST function code and configuration at the time that you created them. In Auto mode, Lambda automatically updates the runtime version of published function versions during phase two of the runtime version rollout. In Function update mode, Lambda doesn't update the runtime version of published function versions.

Published function versions using Function update mode therefore create a static snapshot of the function code, configuration, and runtime version. By using Function update mode with function versions, you can synchronize runtime updates with your deployments. You can also coordinate rollback of code, configuration, and runtime versions by redirecting traffic to an earlier published function version. You can integrate this approach into your continuous integration and continuous delivery (CI/CD) for fully automatic rollback in the rare event of runtime update incompatibility. When using this approach, you must update your function regularly and publish new function versions to pick up the latest runtime updates. For more information, see Shared responsibility model.

Identifying runtime version changes

The runtime version number and ARN are logged in the INIT_START log line, which Lambda emits to CloudWatch Logs each time that it creates a new execution environment. Because the execution environment uses the same runtime version for all function invocations, Lambda emits the INIT_START log line only when Lambda executes the init phase. Lambda doesn't emit this log line for each function invocation. Lambda emits the log line to CloudWatch Logs, but it is not visible in the console.

Example INIT_START log line
INIT_START Runtime Version: python:3.9.v14    Runtime Version ARN: arn:aws:lambda:eu-south-1::runtime:7b620fc2e66107a1046b140b9d320295811af3ad5d4c6a011fad1fa65127e9e6I

Rather than working directly with the logs, you can use Amazon CloudWatch Contributor Insights to identify transitions between runtime versions. The following rule counts the distinct runtime versions from each INIT_START log line. To use the rule, replace the example log group name /aws/lambda/* with the appropriate prefix for your function or group of functions.

{ "Schema": { "Name": "CloudWatchLogRule", "Version": 1 }, "AggregateOn": "Count", "Contribution": { "Filters": [ { "Match": "eventType", "In": [ "INIT_START" ] } ], "Keys": [ "runtimeVersion", "runtimeVersionArn" ] }, "LogFormat": "CLF", "LogGroupNames": [ "/aws/lambda/*" ], "Fields": { "1": "eventType", "4": "runtimeVersion", "8": "runtimeVersionArn" } }

The following CloudWatch Contributor Insights report shows an example of a runtime version transition as captured by the preceding rule. The orange line shows execution environment initialization for the earlier runtime version (python:3.9.v12), and the blue line shows execution environment initialization for the new runtime version (python:3.9.v14).


        Graph showing the transition from one runtime version to another.

Configure runtime management settings

You can configure runtime management settings using the Lambda console or the Amazon Command Line Interface (Amazon CLI).

Note

You can configure runtime management settings separately for each function version.

To configure how Lambda updates your runtime version (console)
  1. Open the Functions page of the Lambda console.

  2. Choose the name of a function.

  3. On the Code tab, under Runtime settings, choose Edit runtime management configuration.

  4. Under Runtime management configuration, choose one of the following:

    • To have your function update to the latest runtime version automatically, choose Auto.

    • To have your function update to the latest runtime version when you change the function, choose Function update.

    • To have your function update to the latest runtime version only when you change the runtime version ARN, choose Manual.

      Note

      You can find the runtime version ARN under Runtime management configuration. You can also find the ARN in the INIT_START line of your function logs.

  5. Choose Save.

To configure how Lambda updates your runtime version (Amazon CLI)

To configure runtime management for a function, you can use the put-runtime-management-config Amazon CLI command, together with the runtime update mode. When using Manual mode, you must also provide the runtime version ARN.

aws lambda put-runtime-management-config --function-name arn:aws:lambda:eu-west-1:069549076217:function:myfunction --update-runtime-on Manual --runtime-version-arn arn:aws:lambda:eu-west-1::runtime:8eeff65f6809a3ce81507fe733fe09b835899b99481ba22fd75b5a7338290ec1

You should see output similar to the following:

{ "UpdateRuntimeOn": "Manual", "FunctionArn": "arn:aws:lambda:eu-west-1:069549076217:function:myfunction", "RuntimeVersionArn": "arn:aws:lambda:eu-west-1::runtime:8eeff65f6809a3ce81507fe733fe09b835899b99481ba22fd75b5a7338290ec1" }

Shared responsibility model

Lambda is responsible for curating and publishing security updates for all supported managed runtimes and container images. Responsibility for updating existing functions to use the latest runtime version varies depending on which runtime update mode you use.

Lambda is responsible for applying runtime updates to all functions configured to use the Auto runtime update mode.

For functions configured with the Function update runtime update mode, you're responsible for regularly updating your function. Lambda is responsible for applying runtime updates when you make those updates. If you don't update your function, then Lambda doesn't update the runtime. If you don't regularly update your function, then we strongly recommend configuring it for automatic runtime updates so that it continues to receive security updates.

For functions configured to use the Manual runtime update mode, you're responsible for updating your function to use the latest runtime version. We strongly recommend that you use this mode only to roll back the runtime version as a temporary mitigation in the rare event of runtime update incompatibility. We also recommend that you change to Auto mode as quickly as possible to minimize the time in which your functions aren't patched.

If you're using container images to deploy your functions, then Lambda is responsible for publishing updated base images. In this case, you're responsible for rebuilding your function's container image from the latest base image and redeploying the container image.

This is summarized in the following table:

Deployment mode Lambda's responsibility Customer's responsibility
Managed runtime, Auto mode

Publish new runtime versions containing the latest patches.

Apply runtime patches to existing functions.

Roll back to a previous runtime version in the rare event of a runtime update compatibility issue.
Managed runtime, Function update mode Publish new runtime versions containing the latest patches.

Update functions regularly to pick up the latest runtime version.

Switch a function to Auto mode when you're not regularly updating the function.

Roll back to a previous runtime version in the rare event of a runtime update compatibility issue.

Managed runtime, Manual mode Publish new runtime versions containing the latest patches.

Use this mode only for temporary runtime rollback in the rare event of a runtime update compatibility issue.

Switch functions to Auto or Function update mode and the latest runtime version as soon as possible.

Container image Publish new container images containing the latest patches. Redeploy functions regularly using the latest container base image to pick up the latest patches.

For more information about shared responsibility with Amazon, see Shared Responsibility Model on the Amazon Web Services Cloud Security site.

High-compliance applications

To meet patching requirements, Lambda customers typically rely on automatic runtime updates. If your application is subject to strict patching freshness requirements, you may want to limit use of earlier runtime versions. You can restrict Lambda's runtime management controls by using Amazon Identity and Access Management (IAM) to deny users in your Amazon account access to the PutRuntimeManagementConfig API operation. This operation is used to choose the runtime update mode for a function. Denying access to this operation causes all functions to default to the Auto mode. You can apply this restriction across your organization by using a service control policies (SCP). In the event that you must roll back a function to an earlier runtime version, you can grant a policy exception on a case-by-case basis.