Runtime lifecycle
As a runtime publisher, you can use a release lifecycle to show the stage of a customer-managed runtime. The lifecycle tells runtime consumers whether a runtime is in preview, generally available, or deprecated. It also tells them the date when the runtime becomes deprecated. You can also set dates when Lambda starts to block consumers from creating or updating Lambda Event Functions that use the runtime.
The release lifecycle is optional. You can set it on a runtime, on a runtime alias, or on both. This topic is for runtime publishers who set the lifecycle and for runtime consumers who need to understand it.
Telling consumers about lifecycle changes
Lambda doesn't send notifications about customer-managed runtimes. For example, Lambda doesn't create AWS Health events, send emails, or add AWS Trusted Advisor checks when you deprecate a runtime. As the runtime publisher, you must tell your consumers about lifecycle changes.
Lambda shows the release lifecycle to consumers as a property of each runtime alias. Consumers can view it by using the Lambda API. For runtimes in your own account, you can also use the Lambda console. For more information, see How runtime consumers see the lifecycle.
We recommend that you announce lifecycle changes through the channels your consumers already use. Examples include internal portals, email lists, release notes, and the runtime or alias description. Give consumers enough time to migrate before any block date.
Release states and lifecycle dates
You set the lifecycle in the ReleaseLifecycle object. It has the following properties. All properties are optional. You specify dates as UTC dates in yyyy-mm-dd format.
| Property | Description |
|---|---|
|
|
The release state of the runtime or alias. Valid values:
|
|
|
The date when the runtime or alias becomes deprecated. On and after this date, Lambda returns the |
|
|
The date when Lambda starts to block |
|
|
The date when Lambda starts to block |
The three dates don't depend on each other. You can set them in any order. For example, you can block function creation before the deprecation date, or you can deprecate the runtime first and block function creation later.
How Lambda enforces block dates
Block dates take effect on the date that you specify, not on the day after. Starting on that date, Lambda enforces the blocks as follows:
-
On and after the
FunctionCreateBlockDate,CreateFunctionrequests that use the runtime or alias fail. -
On and after the
FunctionUpdateBlockDate,UpdateFunctionCodeandUpdateFunctionConfigurationrequests for functions that use the runtime or alias fail.
Block dates affect only these three function operations. They don't affect invocations.
The DeprecationDate changes the release state that Lambda reports. It doesn't block function operations by itself. To block them, set the block dates.
Deprecation never stops your functions from running. Functions that use the runtime or alias continue to run after the DeprecationDate. They also continue to run after the FunctionCreateBlockDate and the FunctionUpdateBlockDate.
The following table summarizes how block dates and deletion affect function operations. Each column shows the effect of one condition by itself. If more than one condition applies, an operation fails if any of them blocks it.
| Operation | On or after the function create block date | On or after the function update block date | The runtime alias or pinned runtime version is scheduled for deletion |
|---|---|---|---|
Create a function that uses the alias (CreateFunction) |
Fails | Allowed | Fails |
Update the function code (UpdateFunctionCode) |
Allowed | Fails | Fails |
Update the function configuration to specify the alias (UpdateFunctionConfiguration) |
Allowed | Fails | Fails |
Update other function configuration, such as memory or timeout (UpdateFunctionConfiguration) |
Allowed | Fails | Fails |
| Pin the function to a runtime version (Manual mode) | Allowed | Allowed. Switching the function back to Auto mode fails. | Fails if the version that you pin to is scheduled for deletion. Pinning to an available version works, and you can then update the function again. |
| Invoke the function | Allowed | Allowed | Depends on whether the runtime version or runtime alias is scheduled for deletion, and on the function's runtime update mode. For details, see How deletion affects functions. |
On or after the function update block date, you can still update the function configuration to move the function to a different alias or runtime.
Block dates don't apply to functions in Manual mode. To return such a function to Auto or Function update mode, its alias must not be blocked.
Consumers can't override block dates for customer-managed runtimes. A consumer who needs more time can create their own customer-managed runtime from your runtime images, if you make the images available. For more information, see Creating a runtime and Building runtime images.
You can also stop consumers from using a runtime by removing their permissions from the runtime's resource-based policy. This blocks new CreateFunction and UpdateFunctionConfiguration requests that reference the runtime. It doesn't affect functions that already use it. Unlike block dates, a permission change blocks both operations at once. For more information, see Sharing and controlling access to customer-managed runtimes.
Rules for release states and dates
Lambda makes sure that the ReleaseState and DeprecationDate agree. The following rules apply when you create or update a release lifecycle:
-
If you set
ReleaseStatetoDEPRECATED, you must also specify aDeprecationDate. TheDeprecationDatemust be today or earlier. -
If you set
ReleaseStatetoPREVIEWorGA, theDeprecationDatemust be later than today. -
If you specify a
ReleaseLifecyclewithout aReleaseState, Lambda sets the state toGA. If theDeprecationDateis today or earlier, Lambda sets the state toDEPRECATEDinstead.
If your request doesn't follow these rules, it fails with a validation error.
When you read a lifecycle, Lambda calculates the state based on today's UTC date. On and after the DeprecationDate, Lambda always returns the ReleaseState as DEPRECATED. This happens automatically. You don't need to update the state yourself.
When you update a runtime or alias, the lifecycle that you specify replaces the lifecycle already stored on that resource. Lambda doesn't merge the lifecycles field by field, so fields that you omit are removed. If an update request doesn't include ReleaseLifecycle, Lambda clears the existing lifecycle. This applies to every update, including updates that change only other settings, such as the description. The replacement applies only to the resource that you update. It doesn't combine an alias lifecycle with the runtime lifecycle.
Follow these practices when you update a runtime or alias:
-
To change one lifecycle field, specify the complete lifecycle in your update request. Include all the fields that you want to keep.
-
To keep the lifecycle unchanged when you update other settings, such as the description, include the current lifecycle in the request.
-
To get the current lifecycle, run the
get-runtimecommand for a runtime, or theget-runtime-aliascommand for an alias. Theget-runtime-aliasresponse shows the lifecycle that applies to the alias. If the alias doesn't have its own lifecycle, the response shows the runtime-level lifecycle. In that case, don't add it to the alias update. Otherwise, the alias gets its own lifecycle and no longer follows changes to the runtime-level lifecycle.
If you clear the lifecycle of an alias, the runtime-level lifecycle applies to the alias again.
The get-runtime-alias response doesn't show whether the lifecycle belongs to the alias or to the runtime. To check, compare it with the get-runtime output. If the two match, the alias might not have its own lifecycle.
Runtime-level and alias-level lifecycles
You can set a release lifecycle on a runtime, on individual runtime aliases, or on both. Runtime versions don't have a lifecycle.
-
Runtime level – The lifecycle applies to all aliases of the runtime that don't have their own lifecycle. Use this approach when your aliases are release stages for the same runtime, such as
dev,test, andprod. All stages share one lifecycle, so you set it one time. -
Alias level – The lifecycle applies to one alias. It replaces the runtime-level lifecycle for that alias. Use this approach when your aliases are separate branches of a runtime that you retire at different times. For example, you might have aliases for different operating system versions or major language versions.
If an alias has its own lifecycle, Lambda uses only the alias lifecycle for that alias. Lambda doesn't combine it with the runtime-level lifecycle. The alias doesn't inherit any runtime-level property, even a property that the alias lifecycle doesn't set. If you want an alias to have a block date, set it in the alias lifecycle.
An alias lifecycle is an optional override of the runtime lifecycle. The dates in an alias lifecycle can be earlier or later than the matching dates on the runtime.
For example, a runtime named java8 has two aliases, al2 and al2023. Each alias uses a different version of Amazon Linux. With the following settings, you can retire the al2 branch before the rest of the runtime:
| Resource | Lifecycle set on resource | Effective deprecation date |
|---|---|---|
java8 (runtime) |
DeprecationDate: 2030-06-30 |
2030-06-30 |
al2 (alias) |
DeprecationDate: 2027-06-30 |
2027-06-30. The alias lifecycle replaces the runtime lifecycle. |
al2023 (alias) |
None | 2030-06-30. The alias inherits the runtime lifecycle. |
In this example, if you later add a FunctionUpdateBlockDate to the java8 runtime lifecycle, the block date applies to al2023 but not to al2. The al2 alias uses only its own lifecycle.
How runtime consumers see the lifecycle
Consumers see the release lifecycle as a property of each runtime alias. When you call GetRuntimeAlias or ListRuntimeAliases, the ReleaseLifecycle in the response is the lifecycle that applies to the alias. If the alias has its own lifecycle, Lambda returns it. Otherwise, Lambda returns the runtime-level lifecycle. If neither is set, the response doesn't include ReleaseLifecycle.
For runtimes in your account, the Lambda console also shows lifecycle information. If the runtime is in another account, use the AWS CLI or the Lambda API.
Consumers in another account need the publisher to grant lambda:GetRuntimeAlias and lambda:ListRuntimeAliases in the runtime's resource-based policy. For more information, see Sharing a customer-managed runtime.
If you're a runtime consumer, we recommend that you check the lifecycle of the aliases that your functions use. Plan your migration before the block dates. For instructions, see Viewing lifecycle information.
Comparison with Lambda-managed runtime deprecation
Lifecycles for customer-managed runtimes use the same block-date model as Lambda-managed runtimes. However, the runtime publisher sets the schedule. The following table summarizes the differences. For more information about Lambda-managed runtimes, see Runtime deprecation.
| Topic | Lambda-managed runtimes | Customer-managed runtimes |
|---|---|---|
| Who sets the schedule | AWS, based on the deprecation policy | The runtime publisher |
| Block dates | Lambda blocks function creates at least 30 days after deprecation. Lambda blocks function updates at least 60 days after deprecation. | Optional. You choose the dates, and they can be in any order. |
| Scope | Each runtime identifier, such as python3.14 |
Each runtime, each runtime alias, or both |
| Release states | Supported or deprecated | PREVIEW, GA, or DEPRECATED |
| Notifications | Health Dashboard, email, and AWS Trusted Advisor | None from Lambda. The publisher notifies consumers. |
| Invocations after block dates | Continue | Continue |
Planning a deprecation
To retire a runtime or alias with the least impact on consumers, we recommend the following steps:
-
Publish the successor runtime or alias, so that consumers have a supported target. For more information, see Creating a runtime and Runtime aliases.
-
Set the
DeprecationDateand, if you plan to enforce the schedule, the block dates. For instructions, see Setting the lifecycle for a runtime and Setting the lifecycle for a runtime alias. -
Notify your consumers. Include the dates and the successor runtime or alias.
-
Track migration by monitoring the
RuntimeInvocationsmetric for each alias. For more information, see Monitoring customer-managed runtimes. -
After consumers have migrated, delete the alias, runtime versions, or runtime that you no longer need. For more information, see Deleting and restoring runtimes.
Deleting a runtime alias or runtime version can cause invocations to fail for functions that still use it. Unlike block dates, deletion affects running functions. Before you delete a resource, confirm that consumers no longer use it.
Setting the lifecycle for a runtime
You can set the release lifecycle when you create a runtime, or add or change it later. A runtime-level lifecycle applies to every alias that doesn't have its own lifecycle.
To set the lifecycle for a runtime (console)
-
Open the Runtimes page
of the Lambda console. -
Choose the runtime.
-
Choose Manage runtime lifecycle.
-
For Release status, select a release status.
-
Enter the dates that you want to set for Deprecation date, Block function creation, and Block function update.
-
Choose Save settings.
The dates are optional. If you set the release status to Deprecated, the deprecation date is required and must be today or earlier.
To set the lifecycle for a new runtime (AWS CLI)
-
To set the lifecycle when you create a runtime, run the
create-runtimecommand with the--release-lifecycleoption. The following example creates a runtime namedcompanyphp8in thePREVIEWstate.aws lambda-core create-runtime \ --namecompanyphp8\ --description "PHP 8 runtime for Example Corp" \ --release-lifecycle ReleaseState=PREVIEW \ --region us-east-1
To set or change the lifecycle for an existing runtime (AWS CLI)
-
To set or change the lifecycle of an existing runtime, run the
update-runtimecommand with the--release-lifecycleoption. You can use shorthand syntax or JSON. The following example makes thecompanyphp8runtime generally available and sets its deprecation and block dates.aws lambda-core update-runtime \ --runtime-namecompanyphp8\ --release-lifecycle '{"ReleaseState":"GA","DeprecationDate":"2027-06-30","FunctionCreateBlockDate":"2027-06-30","FunctionUpdateBlockDate":"2027-09-30"}' \ --region us-east-1You should see output similar to the following:
{ "Arn": "arn:aws:lambda:us-east-1:123456789012:runtime/companyphp8", "Name": "companyphp8", "Description": "PHP 8 runtime for Example Corp", "ReleaseLifecycle": { "ReleaseState": "GA", "DeprecationDate": "2027-06-30", "FunctionCreateBlockDate": "2027-06-30", "FunctionUpdateBlockDate": "2027-09-30" }, "Created": "2026-10-01T10:05:17.443Z", "LastModified": "2026-10-05T14:38:52.344Z" }The
update-runtimecommand replaces the runtime's stored lifecycle with the lifecycle in your request. To change only one property, specify the complete lifecycle, including the values that you want to keep. The following example moves the function update block date and keeps the other values from the previous example.aws lambda-core update-runtime \ --runtime-namecompanyphp8\ --release-lifecycle '{"ReleaseState":"GA","DeprecationDate":"2027-06-30","FunctionCreateBlockDate":"2027-06-30","FunctionUpdateBlockDate":"2027-12-31"}' \ --region us-east-1
Setting the lifecycle for a runtime alias
You can set a release lifecycle on an existing alias in the Lambda console. With the AWS CLI, you can set it when you create the alias with the create-runtime-alias command, or later with the update-runtime-alias command.
To set the lifecycle for a runtime alias (console)
-
Open the Runtimes page
of the Lambda console. -
Choose the runtime, and then choose the Aliases tab.
-
Select the runtime alias that you want to update.
-
Choose Alias actions, and then choose Manage alias lifecycle.
-
For Release status, select a release status. If the runtime is deprecated and you want functions to keep using this alias, set a future deprecation date for the alias. The alias lifecycle overrides the runtime lifecycle. For more information, see Runtime-level and alias-level lifecycles.
-
Enter the dates that you want to set for Deprecation date, Block function creation, and Block function update.
-
Choose Save settings.
The dates are optional. If you set the release status to Deprecated, the deprecation date is required and must be today or earlier.
To set the lifecycle for a runtime alias (AWS CLI)
-
The
update-runtime-aliascommand requires the--runtime-versionoption. To keep the alias on its current runtime version, specify the version that the alias already uses. To find it, run theget-runtime-aliascommand. For an example, see Example: Deprecating a runtime alias.The following example sets the lifecycle of the
al2alias of thejava8runtime. The alias keeps runtime version2026-09-15.1. If the alias already has a lifecycle, the lifecycle in this request replaces it.aws lambda-core update-runtime-alias \ --runtime-namejava8\ --nameal2\ --runtime-version2026-09-15.1\ --release-lifecycle '{"DeprecationDate":"2027-06-30","FunctionCreateBlockDate":"2027-06-30","FunctionUpdateBlockDate":"2027-09-30"}' \ --region us-east-1To set the lifecycle when you create an alias, add the same
--release-lifecycleoption to thecreate-runtime-aliascommand.
Viewing lifecycle information
Publishers and consumers can view the lifecycle that applies to an alias. Publishers can also view the runtime-level lifecycle.
In the Lambda console, the lifecycle of each alias appears in the list of aliases on the runtime's Aliases tab.
If the runtime is in another account, you can't view it in the Lambda console. Use the AWS CLI instead.
To view the lifecycle of a runtime alias (AWS CLI)
-
To view the lifecycle that applies to an alias, run the
get-runtime-aliascommand. The following example gets theal2023alias of thejava8runtime. This alias doesn't have its own lifecycle, so the response shows the runtime-level lifecycle.aws lambda-core get-runtime-alias \ --runtime-namejava8\ --nameal2023\ --region us-east-1You should see output similar to the following:
{ "Name": "al2023", "Arn": "arn:aws:lambda:us-east-1:123456789012:runtime/java8/alias/al2023", "RuntimeVersion": "2026-09-15.2", "RuntimeVersionArn": "arn:aws:lambda:us-east-1:123456789012:runtime/java8/version/2026-09-15.2", "State": "ACTIVE", "Description": "Java 8 on Amazon Linux 2023", "Compatibility": { "Architectures": ["x86_64", "arm64"], "IntegrationModels": ["RuntimeAPI"], "ManagedInstances": "Supported" }, "ReleaseLifecycle": { "ReleaseState": "GA", "DeprecationDate": "2030-06-30" }, "Created": "2026-09-15T09:12:44.102Z", "LastModified": "2026-09-20T16:03:21.876Z" } -
(Optional) To view the lifecycle of every alias of a runtime, run the
list-runtime-aliasescommand. Consumers in other accounts can specify the runtime ARN instead of the runtime name.aws lambda-core list-runtime-aliases \ --runtime-namearn:aws:lambda:us-east-1:123456789012:runtime/java8\ --region us-east-1 -
(Optional) To view the runtime-level lifecycle, run the
get-runtimecommand.aws lambda-core get-runtime \ --runtime-namejava8\ --region us-east-1
Example: Deprecating a runtime alias
In this example, you're the publisher of the java8 runtime. You want to retire the al2 alias and move consumers to the al2023 alias. The runtime itself stays supported until 2030-06-30. You set an alias-level lifecycle on al2 that deprecates it and blocks function creation on 2027-06-30. It blocks function updates on 2027-09-30.
To deprecate a runtime alias (AWS CLI)
-
To confirm that the successor alias is ready, run the
get-runtime-aliascommand foral2023. Check that itsStateisACTIVE.aws lambda-core get-runtime-alias \ --runtime-namejava8\ --nameal2023\ --region us-east-1 -
To find the runtime version that
al2uses, run theget-runtime-aliascommand foral2. Note theRuntimeVersionvalue in the response, such as2026-09-15.1.aws lambda-core get-runtime-alias \ --runtime-namejava8\ --nameal2\ --region us-east-1 -
To set the alias lifecycle, run the
update-runtime-aliascommand. Specify the current runtime version so that the alias doesn't move to a different version.aws lambda-core update-runtime-alias \ --runtime-namejava8\ --nameal2\ --runtime-version2026-09-15.1\ --description "Deprecation scheduled for 2027-06-30. Migrate to the al2023 alias." \ --release-lifecycle '{"DeprecationDate":"2027-06-30","FunctionCreateBlockDate":"2027-06-30","FunctionUpdateBlockDate":"2027-09-30"}' \ --region us-east-1You should see output similar to the following:
{ "Name": "al2", "Arn": "arn:aws:lambda:us-east-1:123456789012:runtime/java8/alias/al2", "RuntimeVersion": "2026-09-15.1", "RuntimeVersionArn": "arn:aws:lambda:us-east-1:123456789012:runtime/java8/version/2026-09-15.1", "State": "ACTIVE", "Description": "Deprecation scheduled for 2027-06-30. Migrate to the al2023 alias.", "Compatibility": { "Architectures": ["x86_64", "arm64"], "IntegrationModels": ["RuntimeAPI"], "ManagedInstances": "Supported" }, "ReleaseLifecycle": { "ReleaseState": "GA", "DeprecationDate": "2027-06-30", "FunctionCreateBlockDate": "2027-06-30", "FunctionUpdateBlockDate": "2027-09-30" }, "Created": "2026-03-02T11:20:05.318Z", "LastModified": "2026-10-05T15:47:10.529Z" }The
ReleaseStateisGAuntil2027-06-30. On that date, Lambda returnsDEPRECATEDautomatically. -
Notify the consumers of the
al2alias. Include the deprecation date, the block dates, and the successor alias. -
Monitor the
RuntimeInvocationsmetric for theal2alias to track migration. For more information, see Monitoring customer-managed runtimes. -
After consumers stop using the alias, delete it. For more information, see Deleting and restoring runtimes.