Runtime aliases
A runtime alias is a name that points to one runtime version. Functions always use a customer-managed runtime through an alias. As a runtime publisher, you roll out an update by pointing an alias to a new version. You roll back by pointing it to the old version. This topic explains how aliases work and how to manage them.
Runtime consumers can also use this topic to learn when alias updates reach their functions, and how to pick an alias.
How runtime aliases work
Each alias belongs to one runtime, and points to one version of that runtime. To use a customer-managed runtime, a runtime consumer sets the function's runtime to custom. The consumer then specifies the runtime ARN and an alias name in the function's runtime configuration. For example:
aws lambda create-function \ --function-namemy-function\ --runtime custom \ --runtime-config RuntimeArn=arn:aws:lambda:us-east-1:123456789012:runtime/companyphp8,RuntimeAlias=prod\ ...
For more information about how consumers configure functions, see Using a customer-managed runtime.
Each alias has an Amazon Resource Name (ARN) in the format arn:aws:lambda:.region:account-id:runtime/runtime-name/alias/alias-name
For example, the prod alias of the companyphp8 runtime has the ARN arn:aws:lambda:us-east-1:123456789012:runtime/companyphp8/alias/prod.
When you point an alias to a different version, functions that use the alias in the Auto runtime update mode move to that version at their next cold start. You don't need to update or redeploy these functions. Functions in other runtime update modes don't move automatically. For more information, see How alias updates reach functions. To roll back, you point the alias back to the previous runtime version.
No function uses a new runtime version until an alias points to it. The exception is a function that a consumer pins to that version by using the Manual runtime update mode.
How alias updates reach functions
When a function picks up an alias change depends on its runtime update mode. Consumers set the mode with runtime management controls. For more information, see Runtime update modes and Managing Lambda runtime updates.
The following table shows when Lambda resolves the alias to a runtime version for each mode.
| Runtime update mode | When Lambda resolves the alias |
|---|---|
| Auto (default) | At each cold start. The function picks up an alias change the next time Lambda initializes a new execution environment. |
| Function update | When you create or update the function. This includes calls to CreateFunction, UpdateFunctionCode, and UpdateFunctionConfiguration. |
| Manual | Never. Lambda ignores the alias, and the function uses the runtime version that you pin it to. |
With the Auto mode, an alias update doesn't reach all functions at once. Lambda replaces execution environments from time to time, so the update rolls out gradually as new environments start. Environments that are already running keep the old version until Lambda replaces them.
Customer-managed runtimes don't use the two-phase rollout that Lambda uses for Lambda-managed runtimes. You control the pace of the rollout by choosing when to update each alias. For more information, see Deploying runtime updates.
Alias strategies
You decide how many aliases to create, and which version each alias points to. The following strategies are common. Other patterns are also possible.
-
Single alias – Create one alias, such as
stable, that all functions use. This strategy is simple and works well while you build your runtime. -
Staged by environment – Create one alias for each stage of your release process, such as
dev,test, andprod. You roll out each new runtime version to each alias in turn. Consumers can then find issues in dev and test before the update reaches prod. -
Semantic versioning – The runtime represents a major version, and each alias represents a minor version. You create a runtime version for each patch release, and point only the matching minor-version alias to it. Consumers choose a minor version and receive patches automatically. Consumers decide when to move their functions to a new minor version.
The following table shows an example of the staged strategy for the companyphp8 runtime. The publisher has rolled out version v8.3.2 to the dev and test aliases, but not yet to prod.
| Alias | Runtime version |
|---|---|
dev |
v8.3.2 |
test |
v8.3.2 |
prod |
v8.3.1 |
The following table shows an example of the semantic versioning strategy for the companyphp8 runtime. Each patch version maps only to its own minor-version alias. For example, version v8.3.2 never maps to the php8.4 alias.
| Alias | Runtime version |
|---|---|
php8.3 |
v8.3.2 |
php8.4 |
v8.4.1 |
Alias compatibility
Each alias has a Compatibility object that tells consumers what they can rely on when they use the alias. It includes the following fields:
-
Architectures– The instruction set architectures that functions can use with the alias:x86_64,arm64, or both. -
IntegrationModels– How the runtime integrates with Lambda. The value isRuntimeAPI, which means that the runtime can be used with Lambda Event Functions. -
ManagedInstances– Whether functions on Lambda Managed Instances can use the alias.
You don't set alias compatibility directly. There's no compatibility option on the operations that create or update an alias. Instead, the alias mirrors the compatibility of the runtime version that it points to. A runtime version takes its compatibility from the labels and platforms in its container image. When you point an alias to a different version, the alias compatibility changes to match that version. For what each capability means and how image labels and platforms set it, see Architectures and feature compatibility. For how a version gets its compatibility, see Runtime version compatibility.
How Lambda checks alias compatibility
Lambda uses alias compatibility in the following ways:
-
When you point an alias to a version – You can't point an alias to a runtime version that drops a capability or architecture that the alias's current version supports. The update fails unless the new version supports at least every capability and architecture of the current version. This rule protects functions that already use the alias.
-
When a consumer creates or updates a function – Lambda checks the function against the compatibility of the alias. The function's architecture must be one of the alias's
Architectures. If the function runs on Lambda Managed Instances, the alias must support Lambda Managed Instances. Otherwise, the request fails.
Because you can't point an alias to a version that drops a capability, an alias never takes away a capability or architecture that consumers rely on.
Add a capability or architecture to an alias
Because an alias mirrors the version that it points to, you add a capability or architecture to an alias by pointing it to a version that has the capability. Follow these steps:
-
Build an image that supports the new capability or architecture. For a capability, add the matching label. For an architecture, build the image for that platform. For more information, see Architectures and feature compatibility.
-
Publish a runtime version from the image. For more information, see Runtime versions.
-
Point the alias to the new version. The alias then gains the capability or architecture. For instructions, see Update an alias to roll out a runtime update.
Adding a capability or architecture doesn't affect existing functions.
Stop offering a capability
You can't remove a capability or architecture from an alias by pointing the alias to a version that drops it. Lambda blocks that update to protect functions that already use the alias. To stop offering a capability, create a new alias (or a new runtime) for versions that don't have the capability. Then ask consumers to move their functions to it when they're ready. For more information, see Create a runtime alias.
After Lambda permanently deletes an alias, you can re-create an alias with the same name. If the re-created alias points to a version that doesn't support a capability that a function needs, that function becomes incompatible with its runtime version. The function enters the Inactive state. Existing execution environments continue to handle invocations, but invocations that require a cold start fail. After you restore compatibility, the function returns to the Active state automatically. For more information, see Runtime lifecycle and function states.
Alias lifecycle
You can set a release lifecycle on the runtime and on each alias. The lifecycle includes the release state and the deprecation date. It also includes the dates when Lambda blocks function creation and updates. An alias lifecycle is useful when your aliases represent separate branches of a runtime, such as al2023 and al2027. You can then deprecate each branch independently.
An alias lifecycle is optional. If you set a lifecycle on an alias, the alias lifecycle replaces the runtime lifecycle for that alias. The alias dates can be earlier or later than the runtime dates. For more information, see Runtime lifecycle.
Alias states
A runtime alias is in one of the following states:
-
CREATING– Lambda is creating the alias. -
ACTIVE– The alias is ready to use. -
UPDATING– Lambda is updating the alias. -
PENDING_DELETION– The alias is scheduled for deletion. You can restore it until the waiting period ends. For more information, see Resources scheduled for deletion. -
DELETING– Lambda is deleting the alias.
You can update an alias only when it's in the ACTIVE state. You can't change the waiting period of an alias that's in the PENDING_DELETION state. If you delete an alias that's already scheduled for deletion, the request succeeds, but it doesn't change the alias's waiting period. To reschedule the deletion, restore the alias, and then delete it again. For more information, see Rescheduling a deletion.
An alias that's scheduled for deletion keeps its name until Lambda permanently deletes it. Until then, you can't create an alias with the same name in the runtime. For more information, see Resources scheduled for deletion.
Alias names
Alias names must meet the following requirements:
-
Contain 1–128 characters
-
Contain only uppercase and lowercase letters, numbers, underscores (
_), periods (.), and hyphens (-) -
Start and end with a letter, number, or underscore
Alias names are case-sensitive. The alias name becomes part of the alias ARN.
Permissions for runtime aliases
To manage runtime aliases, runtime publishers need the following IAM permissions:
-
lambda:CreateRuntimeAlias -
lambda:GetRuntimeAlias -
lambda:UpdateRuntimeAlias -
lambda:DeleteRuntimeAlias -
lambda:ListRuntimeAliases
To use an alias in a function, runtime consumers need the lambda:AssociateRuntimeAlias permission on the alias ARN. Lambda checks this permission when the consumer creates the function or changes its runtime configuration, not at invocation. For more information, see Sharing and controlling access to customer-managed runtimes.
Create a runtime alias
Create an alias so that functions can use a runtime version. After you create the alias, share the runtime ARN and alias name with your runtime consumers.
Prerequisites
-
A runtime version in the
ACTIVEstate. For more information, see Runtime versions. -
The
lambda:CreateRuntimeAliaspermission.
To create a runtime alias (console)
-
Open the Runtimes page
of the Lambda console. -
Choose the runtime, and then choose the Aliases tab.
-
Choose Create alias.
-
For Runtime alias name, enter a name for the alias. The alias name must be unique for this runtime.
-
Optionally, for Alias description, enter a description.
-
For Runtime version, choose an existing runtime version from the dropdown list.
-
Choose Create alias.
To create a runtime alias (AWS CLI)
-
To create the alias, run the
create-runtime-aliascommand.aws lambda-core create-runtime-alias \ --runtime-namecompanyphp8\ --nameprod\ --runtime-versionv8.3.1\ --description "Production alias for the companyphp8 runtime"For
--runtime-name, you can specify the runtime name or the runtime ARN. For--runtime-version, specify the name of the runtime version. The alias takes its compatibility from this version. You can't set compatibility on the alias directly. For more information, see Alias compatibility. You can also specify--release-lifecycleto set a lifecycle for the alias. For more information, see Runtime lifecycle.You should see output similar to the following:
{ "Name": "prod", "Arn": "arn:aws:lambda:us-east-1:123456789012:runtime/companyphp8/alias/prod", "RuntimeVersion": "v8.3.1", "RuntimeVersionArn": "arn:aws:lambda:us-east-1:123456789012:runtime/companyphp8/version/v8.3.1", "State": "CREATING", "Description": "Production alias for the companyphp8 runtime", "Compatibility": { "Architectures": [ "x86_64", "arm64" ], "IntegrationModels": [ "RuntimeAPI" ], "ManagedInstances": "Supported" }, "Created": "2026-10-05T17:00:00.000Z", "LastModified": "2026-10-05T17:00:00.000Z" } -
To check that the alias is ready to use, run the
get-runtime-aliascommand.aws lambda-core get-runtime-alias \ --runtime-namecompanyphp8\ --nameprodRepeat this command until the value of
StateisACTIVE.Alternatively, to wait until the alias is ready, run the following command:
aws lambda-core wait runtime-alias-active \ --runtime-namecompanyphp8\ --nameprodThe command returns when the alias is
ACTIVE.
When the alias is ACTIVE, consumers can configure functions to use it. For more information, see Using a customer-managed runtime.
Update an alias to roll out a runtime update
To roll out a new runtime version, update the alias to point to that version. Functions that use the alias in Auto mode move to the new version at their next cold start, without any function update. Functions in other modes don't move automatically. For more information, see Controlling runtime updates.
Prerequisites
-
A new runtime version in the
ACTIVEstate. -
An alias in the
ACTIVEstate. -
The
lambda:UpdateRuntimeAliaspermission.
To update 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 to update.
-
Choose Alias actions, and then choose Update alias.
-
Update the Alias description, choose a different Runtime version from the dropdown list, or both.
-
Choose Update alias.
To update a runtime alias (AWS CLI)
-
To point the alias to the new runtime version, run the
update-runtime-aliascommand.aws lambda-core update-runtime-alias \ --runtime-namecompanyphp8\ --nameprod\ --runtime-versionv8.3.2The
--runtime-versionparameter is required. If you omit--description, the description doesn't change. If you specify--release-lifecycle, the lifecycle that you specify replaces the existing alias lifecycle. If you omit--release-lifecycle, Lambda clears any lifecycle on the alias, and the runtime-level lifecycle applies. To keep the alias lifecycle, include the complete lifecycle in each update. For more information, see Rules for release states and dates.If the new version drops a capability or architecture that the alias's current version supports, the command fails. For more information, see Alias compatibility.
-
To verify the update, run the
get-runtime-aliascommand.aws lambda-core get-runtime-alias \ --runtime-namecompanyphp8\ --nameprodWhen the update is complete,
StateisACTIVEandRuntimeVersionisv8.3.2.
Every update-runtime-alias request must specify the runtime version, even when you change only other settings, such as the description. The RuntimeVersion parameter is required. If two updates run at the same time, one can overwrite the other and move the alias back to an earlier version. To avoid this, follow these practices:
-
Before you update an alias, run the
get-runtime-aliascommand to get its current runtime version. If you don't want to change the version, pass the current version in your update request. -
If the alias has its own lifecycle, include the complete lifecycle in the
--release-lifecycleoption of every update request. If you omit--release-lifecycle, Lambda clears the alias lifecycle. -
Run updates to an alias one at a time. For example, run your deployment pipelines one at a time.
Functions in Auto mode pick up the new version at their next cold start. Functions in Function update mode pick it up the next time that the function owner updates them. Functions in Manual mode don't change. For more information, see How alias updates reach functions. To monitor a rollout, see Deploying runtime updates.
Roll back a runtime update
If a new version causes problems, point the alias back to the old version. Functions in Auto mode pick up the previous version at their next cold start.
To roll back a runtime alias in the console, follow the steps in To update a runtime alias (console). For Runtime version, choose the previous runtime version.
To roll back a runtime alias (AWS CLI)
-
To point the alias back to the previous runtime version, run the
update-runtime-aliascommand.aws lambda-core update-runtime-alias \ --runtime-namecompanyphp8\ --nameprod\ --runtime-versionv8.3.1 -
To verify the rollback, run the
get-runtime-aliascommand.aws lambda-core get-runtime-alias \ --runtime-namecompanyphp8\ --nameprodWhen the rollback is complete,
StateisACTIVEandRuntimeVersionisv8.3.1.
Runtime consumers can also roll back an individual function. To do this, the consumer pins the function to an earlier runtime version by using the Manual runtime update mode. For more information, see Using a customer-managed runtime.
View runtime aliases
You can view the details of one alias, or list all aliases for a runtime.
In the Lambda console, the Aliases tab of the runtime's page lists the aliases for the runtime.
To view runtime aliases (AWS CLI)
-
To view the details of one alias, run the
get-runtime-aliascommand.aws lambda-core get-runtime-alias \ --runtime-namecompanyphp8\ --nameprodThe output includes the runtime version that the alias points to, the alias state, its compatibility, and its effective release lifecycle.
-
To list all aliases for a runtime, run the
list-runtime-aliasescommand.aws lambda-core list-runtime-aliases \ --runtime-namecompanyphp8You should see output similar to the following:
{ "Items": [ { "Name": "prod", "Arn": "arn:aws:lambda:us-east-1:123456789012:runtime/companyphp8/alias/prod", "RuntimeVersion": "v8.3.1", "RuntimeVersionArn": "arn:aws:lambda:us-east-1:123456789012:runtime/companyphp8/version/v8.3.1", "State": "ACTIVE", "Description": "Production alias for the companyphp8 runtime", "Compatibility": { "Architectures": [ "x86_64", "arm64" ], "IntegrationModels": [ "RuntimeAPI" ], "ManagedInstances": "Supported" }, "Created": "2026-10-05T17:00:00.000Z", "LastModified": "2026-10-05T17:00:00.000Z" } ] }The command returns all aliases. To limit the output, use
--max-items.
Example: Staged rollout across aliases
The following example rolls out runtime version v8.3.2 through the dev, test, and prod aliases of the companyphp8 runtime. Between each step, check that functions that use the updated alias work as expected. For guidance on monitoring, see Deploying runtime updates.
# Step 1: Roll out to development aws lambda-core update-runtime-alias --runtime-name companyphp8 --name dev --runtime-version v8.3.2 # Step 2: After validating dev, roll out to test aws lambda-core update-runtime-alias --runtime-name companyphp8 --name test --runtime-version v8.3.2 # Step 3: After validating test, roll out to production aws lambda-core update-runtime-alias --runtime-name companyphp8 --name prod --runtime-version v8.3.2
If you find a problem at any stage, roll back that alias to v8.3.1, and don't update the later aliases.
Delete a runtime alias
You can't delete a runtime version while an alias points to it. After you delete the alias, you can delete the version. For more information about deleting aliases and other runtime resources, see Deleting and restoring runtimes.
Next steps
After you create your aliases, see the following topics:
-
To share your runtime with consumers and grant them access to aliases, see Sharing and controlling access to customer-managed runtimes.
-
To learn how consumers configure functions to use an alias, see Using a customer-managed runtime.
-
To plan and monitor runtime update rollouts, see Deploying runtime updates.