Creating a runtime
As a runtime publisher, you start by creating a runtime. The runtime is the top-level resource for a customer-managed runtime. It holds the name, Amazon Resource Name (ARN), description, license information, and lifecycle information for the runtime as a whole. It's also where you control who can use the runtime. For an overview of customer-managed runtimes and the resource model, see Customer-managed runtimes.
This topic explains runtime properties, tags, and access, and then shows you how to create, update, and tag a runtime.
Sections
About the runtime resource
A runtime is the parent of its runtime versions and runtime aliases. Runtime versions define the contents of the runtime, and runtime aliases point functions to a runtime version. Runtimes are Regional resources. You must create a runtime in each AWS Region where you want to use it. For more information, see Deploying runtimes in multiple Regions.
Functions can't use a new runtime yet. A new runtime has no runtime versions and no runtime aliases. To make a runtime available to functions, complete the following workflow:
-
Build a runtime image and push it to Amazon ECR. For more information, see Building runtime images.
-
Create the runtime, as described in this topic.
-
Create a runtime version from the image. For more information, see Runtime versions.
-
Create a runtime alias that points to the runtime version. For more information, see Runtime aliases.
-
Grant other accounts access to the runtime, if needed. For more information, see Sharing and controlling access to customer-managed runtimes.
You can create the runtime before or after you build the image. You must create the runtime before you create any runtime versions or runtime aliases.
Lambda creates a runtime synchronously. The runtime is available as soon as the create request succeeds.
Runtime properties
A runtime has the following properties:
Name-
The name of the runtime. The name is required, and you can't change it after you create the runtime. Lambda uses the name as part of the runtime ARN. The name must meet the following requirements:
-
Contain 2–128 characters
-
Contain only lowercase letters, numbers, underscores (
_), periods (.), and hyphens (-) -
Start and end with a lowercase letter or a number
-
Be unique among the runtimes in your account in the AWS Region
We recommend that you include the language or framework and its major version in the name, for example,
companyphp8ormynode24. This helps runtime consumers identify the runtime. You can also create a separate runtime for each major version. -
Description-
(Optional) A description of the runtime. Use the description to tell runtime consumers what the runtime is for and what it contains.
LicenseInfo-
(Optional) License information for the runtime. A runtime image often includes third-party software, such as a language runtime, libraries, and tools. Use this property to list the licenses for this software. For example, you can list the license names or provide a link to a page that describes them.
If you omit
DescriptionorLicenseInfo, Lambda returns an empty string for it. ReleaseLifecycle-
(Optional) The release state and deprecation dates for the runtime. You can set this property when you create the runtime or later. You can also set lifecycle information on individual runtime aliases. For more information, see Runtime lifecycle.
After you create a runtime, Lambda also returns the following read-only properties:
-
Arn– The ARN of the runtime. -
Created– The time when you created the runtime. -
LastModified– The time when you last updated the runtime. -
State– The state of the runtime. This property appears in the output only when the runtime is scheduled for deletion. In that case, its value isPENDING_DELETION. -
PendingDeletionAt– The date and time when Lambda permanently deletes the runtime. For more information, see Deleting and restoring runtimes.
A runtime ARN has the format arn:aws:lambda:.region:account-id:runtime/runtime-name
For example, the ARN of a runtime named companyphp8 in account 123456789012 in the US East (N. Virginia) Region is arn:aws:lambda:us-east-1:123456789012:runtime/companyphp8. The ARNs of runtime versions and runtime aliases extend the runtime ARN. For more information, see Runtime versions and Runtime aliases.
Operations on runtime versions and runtime aliases accept either the runtime name or the full runtime ARN to identify the runtime.
Runtime tags
You can add tags to a runtime to organize your resources, track costs, and control access. You can add tags when you create the runtime. To add, change, or remove tags later, use the Lambda tagging operations TagResource, UntagResource, and ListTags with the runtime ARN.
The response from creating a runtime doesn't include tags. To view the tags on a runtime, use ListTags.
You can tag runtimes only. You can't tag runtime versions or runtime aliases.
You can use tags in IAM policies to control access to runtimes with attribute-based access control (ABAC). For more information, see Sharing and controlling access to customer-managed runtimes and Using attribute-based access control in Lambda. For general information about tags in Lambda, see Using tags on Lambda Event Functions.
Runtime operations support the aws:RequestTag/, keyaws:TagKeys, and aws:ResourceTag/ condition keys. For runtime versions and aliases, keyaws:ResourceTag uses the runtime's tags.
Runtime access
By default, only the AWS account that owns a runtime can use it. To share the runtime with other accounts, with an organization, or publicly, you attach a resource-based policy to the runtime. You control access at the runtime level. For more information, see Sharing and controlling access to customer-managed runtimes.
If you share a runtime publicly, any AWS account can use the runtime in its functions. Before you share a runtime publicly, review what the runtime image contains. Also review the licenses of the software that the image includes. For more information, see Share a runtime publicly.
Prerequisites
Before you create a runtime, make sure that you meet the following requirements.
Required permissions
To create and manage runtimes, runtime versions, and runtime aliases, your IAM identity needs IAM permissions. For a list of the IAM actions for customer-managed runtimes, see IAM actions. For more information about access control for customer-managed runtimes, see Sharing and controlling access to customer-managed runtimes.
Create a runtime
You can create a runtime by using the Lambda console or the AWS CLI.
Create a runtime (console)
To create a runtime (console)
-
Open the Runtimes page
of the Lambda console. -
Choose Create runtime.
-
In the Runtime basic information pane, for Runtime name, enter a name for your runtime.
-
Optionally, expand Additional settings, and then enter a Runtime description and License information.
-
In the Runtime version configuration pane, for Runtime version name, enter a name for the first runtime version.
-
For Image source, do one of the following:
-
To use an image in your account, make sure that Owned by you is selected. Choose Browse ECR, and then select the Amazon ECR repository and the runtime version image.
-
To use an image that another account shared with you, select Shared with you, and then paste the URI of the container image.
-
-
Optionally, enter Release notes for the runtime version.
-
Optionally, to also create a runtime alias, in the Runtime alias configuration pane, enter a Runtime alias name. You can also enter an Alias description.
In addition to the runtime, the console creates your first runtime version. If you entered an alias name, the console also creates a runtime alias that points to that runtime version.
Create a runtime (AWS CLI)
To create a runtime (AWS CLI)
-
To create the runtime, run the
create-runtimecommand. The following example creates a runtime namedcompanyphp8with a description, license information, and two tags.aws lambda-core create-runtime \ --namecompanyphp8\ --description "PHP 8 runtime with company-approved extensions" \ --license-info "PHP License v3.01. Includes components under the MIT and Apache-2.0 licenses." \ --tagsTeam=platform,Project=runtimesYou should see output similar to the following:
{ "Arn": "arn:aws:lambda:us-east-1:123456789012:runtime/companyphp8", "Name": "companyphp8", "Description": "PHP 8 runtime with company-approved extensions", "LicenseInfo": "PHP License v3.01. Includes components under the MIT and Apache-2.0 licenses.", "Created": "2026-10-05T17:21:09.112Z", "LastModified": "2026-10-05T17:21:09.112Z" }The output doesn't include
ReleaseLifecyclebecause you didn't set it. The output doesn't include tags.If a runtime with the same name already exists in your account and Region, the command fails.
-
Save the value of
Arnfrom the output. You use the runtime ARN to grant access to the runtime and to manage its tags. Runtime consumers use it to configure their functions. -
To verify the runtime, run the
get-runtimecommand. You can specify the runtime name or the runtime ARN.aws lambda-core get-runtime --runtime-namecompanyphp8The output contains the same properties as the output of
create-runtime. -
(Optional) To list all runtimes in your account in the current Region, run the
list-runtimescommand.aws lambda-core list-runtimesYou should see output similar to the following:
{ "Items": [ { "Arn": "arn:aws:lambda:us-east-1:123456789012:runtime/companyphp8", "Name": "companyphp8", "Description": "PHP 8 runtime with company-approved extensions", "LicenseInfo": "PHP License v3.01. Includes components under the MIT and Apache-2.0 licenses.", "Created": "2026-10-05T17:21:09.112Z", "LastModified": "2026-10-05T17:21:09.112Z" } ] }The command returns all runtimes. To limit the output, use
--max-items.
Your runtime now exists, but functions can't use it yet. Next, create a runtime version and a runtime alias. For more information, see Next steps.
Update a runtime
After you create a runtime, you can update its description, license information, and lifecycle information. You can't change the runtime name. To use a different name, create a new runtime.
When you update a runtime, Lambda changes only the properties that you specify. Properties that you omit keep their current values, except for ReleaseLifecycle. The lifecycle that you specify replaces the existing lifecycle. Lambda doesn't merge it field by field. If you omit ReleaseLifecycle, Lambda clears the existing lifecycle. To change one lifecycle field, or to keep the lifecycle when you update other properties, specify the complete lifecycle in your request. For more information about lifecycle settings, see Rules for release states and dates.
Update a runtime (console)
To update a runtime (console)
-
Open the Runtimes page
of the Lambda console. -
Choose the runtime to update.
-
Choose Runtime actions, and then choose Edit basic information.
-
Update the Runtime description, the License information, or both.
-
Choose Save basic information.
The Runtime configuration panel shows the updated runtime description and license information.
Update a runtime (AWS CLI)
To update a runtime (AWS CLI)
-
To update the runtime, run the
update-runtimecommand. The following example changes the description of thecompanyphp8runtime. The license information doesn't change. The example doesn't include the--release-lifecycleoption, so it also clears any lifecycle on the runtime. To keep the lifecycle, run theget-runtimecommand to get the current lifecycle. Then pass the complete lifecycle in the--release-lifecycleoption.aws lambda-core update-runtime \ --runtime-namecompanyphp8\ --description "PHP 8 runtime with company-approved extensions and monitoring agent"You should see output similar to the following:
{ "Arn": "arn:aws:lambda:us-east-1:123456789012:runtime/companyphp8", "Name": "companyphp8", "Description": "PHP 8 runtime with company-approved extensions and monitoring agent", "LicenseInfo": "PHP License v3.01. Includes components under the MIT and Apache-2.0 licenses.", "Created": "2026-10-05T17:21:09.112Z", "LastModified": "2026-10-05T18:02:44.508Z" }To update license information, use the
--license-infooption. To update lifecycle information, use the--release-lifecycleoption. For examples of lifecycle updates, see Runtime lifecycle. -
To verify the change, run the
get-runtimecommand and check the updated property and theLastModifiedvalue.aws lambda-core get-runtime --runtime-namecompanyphp8
Manage runtime tags
To add, view, and remove tags on an existing runtime, use the Lambda tagging commands with the runtime ARN. Tags that you add with tag-resource are added to any existing tags. If a tag key already exists, the new value replaces the existing value.
To manage runtime tags (AWS CLI)
-
To add or change tags, run the
tag-resourcecommand.aws lambda tag-resource \ --resourcearn:aws:lambda:us-east-1:123456789012:runtime/companyphp8\ --tagsCostCenter=1234This command doesn't produce any output.
-
To view the tags on the runtime, run the
list-tagscommand.aws lambda list-tags \ --resourcearn:aws:lambda:us-east-1:123456789012:runtime/companyphp8You should see output similar to the following:
{ "Tags": { "Team": "platform", "Project": "runtimes", "CostCenter": "1234" } } -
To remove tags, run the
untag-resourcecommand with the keys of the tags to remove.aws lambda untag-resource \ --resourcearn:aws:lambda:us-east-1:123456789012:runtime/companyphp8\ --tag-keysCostCenterThis command doesn't produce any output. To verify that Lambda removed the tag, run the
list-tagscommand again.
Next steps
After you create a runtime, complete the following tasks to make it available to functions:
-
To build and push a runtime image to Amazon ECR, see Building runtime images.
-
To create a runtime version from your image, see Runtime versions.
-
To create a runtime alias that functions can reference, see Runtime aliases.
-
To share the runtime with other accounts, see Sharing and controlling access to customer-managed runtimes.