Deploy .NET Lambda functions with container images (original) (raw)

There are three ways to build a container image for a .NET Lambda function:

This page explains how to build, test, and deploy container images for Lambda.

Topics

AWS base images for .NET

AWS provides the following base images for .NET:

Amazon ECR repository: gallery.ecr.aws/lambda/dotnet

Using an AWS base image for .NET

Prerequisites

To complete the steps in this section, you must have the following:

Creating and deploying an image using a base image

In the following steps, you use Amazon.Lambda.Templates and Amazon.Lambda.Tools to create a .NET project. Then, you build a Docker image, upload the image to Amazon ECR, and deploy it to a Lambda function.

  1. Install the Amazon.Lambda.Templates NuGet package.
dotnet new install Amazon.Lambda.Templates
  1. Create a .NET project using the lambda.image.EmptyFunction template.
dotnet new lambda.image.EmptyFunction --name MyFunction --region us-east-1

The project files are stored in the `MyFunction`/src/`MyFunction` directory:

  1. Install the Amazon.Lambda.Tools .NET Global Tool.
dotnet tool install -g Amazon.Lambda.Tools

If Amazon.Lambda.Tools is already installed, make sure that you have the latest version. 

dotnet tool update -g Amazon.Lambda.Tools
  1. Change the directory to`MyFunction`/src/`MyFunction`, if you're not there already.
cd src/MyFunction
  1. Use Amazon.Lambda.Tools to build the Docker image, push it to a new Amazon ECR repository, and deploy the Lambda function.
    For --function-role, specify the role name—not the Amazon Resource Name (ARN)—of the execution role for the function. For example, lambda-role.
dotnet lambda deploy-function MyFunction --function-role lambda-role

For more information about the Amazon.Lambda.Tools .NET Global Tool, see the AWS Extensions for .NET CLI repository on GitHub. 6. Invoke the function. 

dotnet lambda invoke-function MyFunction --payload "Testing the function"

If everything is successful, you see a response similar to the following:
Payload:
{"Lower":"testing the function","Upper":"TESTING THE FUNCTION"}
Log Tail:
INIT_REPORT Init Duration: 9999.81 ms Phase: init Status: timeout
START RequestId: 12378346-f302-419b-b1f2-deaa1e8423ed Version: $LATEST
END RequestId: 12378346-f302-419b-b1f2-deaa1e8423ed
REPORT RequestId: 12378346-f302-419b-b1f2-deaa1e8423ed Duration: 3173.06 ms Billed Duration: 3174 ms Memory Size: 512 MB Max Memory Used: 24 MB 7. Delete the Lambda function. 

dotnet lambda delete-function MyFunction

Using an alternative base image with the runtime interface client

If you use an OS-only base image or an alternative base image, you must include the runtime interface client in your image. The runtime interface client extends the Runtime API, which manages the interaction between Lambda and your function code.

The following example demonstrates how to build a container image for .NET using a non-AWS base image, and how to add the Amazon.Lambda.RuntimeSupport package, which is the Lambda runtime interface client for .NET. The example Dockerfile uses the Microsoft .NET 8 base image.

Prerequisites

To complete the steps in this section, you must have the following:

Creating and deploying an image using an alternative base image

  1. Install the Amazon.Lambda.Templates NuGet package.
dotnet new install Amazon.Lambda.Templates
  1. Create a .NET project using the lambda.CustomRuntimeFunction template. This template includes the Amazon.Lambda.RuntimeSupport package.
dotnet new lambda.CustomRuntimeFunction --name MyFunction --region us-east-1
  1. Navigate to the `MyFunction`/src/`MyFunction` directory. This is where the project files are stored. Examine the following files:
    • aws-lambda-tools-defaults.json – This file is where you specify the command line options when deploying your Lambda function.
    • Function.cs – The code contains a class with a Main method that initializes the Amazon.Lambda.RuntimeSupport library as the bootstrap. The Main method is the entry point for the function's process. The Main method wraps the function handler in a wrapper that the bootstrap can work with. For more information, see Using Amazon.Lambda.RuntimeSupport as a class library in the GitHub repository.
    • MyFunction.csproj – A .NET project file, which lists the files and assemblies that comprise your application.
    • Readme.md – This file contains more information about the sample Lambda function.
  2. Open the aws-lambda-tools-defaults.json file and Add the following lines:
  "package-type": "image",  
  "docker-host-build-output-dir": "./bin/Release/lambda-publish"
Example aws-lambda-tools-defaults.json
{  
  "Information": [  
    "This file provides default values for the deployment wizard inside Visual Studio and the AWS Lambda commands added to the .NET Core CLI.",  
    "To learn more about the Lambda commands with the .NET Core CLI execute the following command at the command line in the project root directory.",  
    "dotnet lambda help",  
    "All the command line options for the Lambda command can be specified in this file."  
  ],  
  "profile": "",  
  "region": "us-east-1",  
  "configuration": "Release",  
  "function-runtime": "provided.al2023",  
  "function-memory-size": 256,  
  "function-timeout": 30,  
  "function-handler": "bootstrap",  
  "msbuild-parameters": "--self-contained true",  
  "package-type": "image",  
  "docker-host-build-output-dir": "./bin/Release/lambda-publish"  
}
  1. Create a Dockerfile in the `MyFunction`/src/`MyFunction` directory. The following example Dockerfile uses a Microsoft .NET base image instead of an AWS base image.
    • Set the FROM property to the base image identifier. The base image and the TargetFramework in the MyFunction.csproj file must both use the same .NET version.
    • Use the COPY command to copy the function into the /var/task directory.
    • Set the ENTRYPOINT to the module that you want the Docker container to run when it starts. In this case, the module is the bootstrap, which initializes the Amazon.Lambda.RuntimeSupport library.
      Note that the example Dockerfile does not include a USER instruction. When you deploy a container image to Lambda, Lambda automatically defines a default Linux user with least-privileged permissions. This is different from standard Docker behavior which defaults to the root user when no USER instruction is provided.
Example Dockerfile
# You can also pull these images from DockerHub amazon/aws-lambda-dotnet:8  
FROM mcr.microsoft.com/dotnet/runtime:9.0  
# Set the image's internal work directory  
WORKDIR /var/task  
    
# Copy function code to Lambda-defined environment variable  
COPY "bin/Release/net9.0/linux-x64"  .  
    
# Set the entrypoint to the bootstrap  
ENTRYPOINT ["/usr/bin/dotnet", "exec", "/var/task/bootstrap.dll"]
  1. Install the Amazon.Lambda.Tools .NET Global Tools extension.
dotnet tool install -g Amazon.Lambda.Tools

If Amazon.Lambda.Tools is already installed, make sure that you have the latest version. 

dotnet tool update -g Amazon.Lambda.Tools
  1. Use Amazon.Lambda.Tools to build the Docker image, push it to a new Amazon ECR repository, and deploy the Lambda function.
    For --function-role, specify the role name—not the Amazon Resource Name (ARN)—of the execution role for the function. For example, lambda-role.
dotnet lambda deploy-function MyFunction --function-role lambda-role

For more information about the Amazon.Lambda.Tools .NET CLI extension, see the AWS Extensions for .NET CLI repository on GitHub. 8. Invoke the function. 

dotnet lambda invoke-function MyFunction --payload "Testing the function"

If everything is successful, you see the following: 

Payload:  
"TESTING THE FUNCTION"  
Log Tail:  
START RequestId: id Version: $LATEST  
END RequestId: id  
REPORT RequestId: id  Duration: 0.99 ms       Billed Duration: 1 ms         Memory Size: 256 MB     Max Memory Used: 12 MB
  1. Delete the Lambda function.
dotnet lambda delete-function MyFunction