Testing and debugging functions that use customer-managed runtimes
A function that uses a customer-managed runtime sets Runtime to custom. Its
RuntimeConfig property specifies the ARN of the runtime and the name of the runtime alias.
sam local invoke, sam local start-api, and sam local start-lambda run the function on the container image of that runtime.
To learn more about customer-managed runtimes, see Using a customer-managed runtime in the AWS Lambda Developer Guide. To build the function, see Building Lambda Event Functions with customer-managed runtimes in AWS SAM.
Local testing
By default, the AWS SAM CLI looks up the runtime image from RuntimeConfig, and
then pulls the image:
-
It asks Lambda which runtime version
RuntimeAliaspoints to, and which image that version uses. -
It uses your AWS credentials and the Region in
RuntimeArn. -
It always uses the runtime version that the alias points to. It ignores RuntimeManagementConfig, including a runtime version that you pinned with
Manualmode.
Local testing needs access that deploying the function doesn't need:
-
The
lambda:GetRuntimeAliasandlambda:GetRuntimeVersionpermissions on the runtime. -
Permission to pull the image from its Amazon ECR repository.
-
Docker signed in to that registry. For more information, see Private registry authentication in Amazon ECR.
If the runtime is in another AWS account, the runtime publisher must also grant the
lambda:GetRuntimeAlias and lambda:GetRuntimeVersion permissions to your account in the
resource-based policy of the runtime. For more information, see Sharing and controlling access to customer-managed
runtimes in the AWS Lambda Developer Guide.
A function that you deploy doesn't need access to the image, because Lambda reads the image itself.
To use a different runtime image, pass it with --invoke-image. The AWS SAM CLI
then doesn't look up RuntimeConfig. The following is an example:
$sam local invokeMyFunction--invoke-image111122223333.dkr.ecr.us-east-1.amazonaws.com/my-python-runtime:v2
The AWS SAM CLI can look up the runtime only when RuntimeArn and
RuntimeAlias are literal values or template parameters. If a value comes from an intrinsic function
that the AWS SAM CLI can't resolve locally, such as Fn::ImportValue, pass the
runtime image with --invoke-image.
Debugging
When you debug, the AWS SAM CLI uses the debug settings of the runtime that
Metadata.BuildMethod names. Debugging works with the following runtime images:
-
Java – Any runtime image.
-
Python, Node.js, and .NET – Only a runtime image built from a Lambda base image for that language, such as
public.ecr.aws/lambda/python:3.12.
Troubleshooting
Not allowed to look up runtime
Problem: A sam local command fails with Not
allowed to look up runtime. Your AWS credentials can't call lambda:GetRuntimeAlias or
lambda:GetRuntimeVersion for the runtime in RuntimeConfig.
Solutions:
-
Get these permissions. If another AWS account owns the runtime, ask the runtime publisher to grant them to your account in the resource-based policy of the runtime.
-
Pass the runtime image with
--invoke-image.
Runtime image can't be pulled
Problem: A sam local command finds the runtime image,
and then fails with an error from Docker, such as no basic auth credentials or
denied.
Solutions:
-
Sign in Docker to the Amazon ECR registry of the runtime image. The following is an example:
$aws ecr get-login-password --regionus-east-1| docker login --username AWS --password-stdin111122223333---dkr---ecr---us-east-1.amazonaws.com.rproxy.goskope.comFor more information, see Private registry authentication in Amazon ECR.
-
If another AWS account owns the repository, ask the runtime publisher to grant your account
ecr:BatchGetImageandecr:GetDownloadUrlForLayerin the repository policy. -
Pass a runtime image that you can pull with
--invoke-image.