Implantar funções do Lambda em .NET com imagens de contêiner

Existem três maneiras de criar uma imagem de contêiner para uma função do Lambda em .NET:

• Usar uma imagem base da AWS para .NET

  As imagens base da AWS são pré-carregadas com um  runtime de linguagem, um cliente de interface de runtime para gerenciar a interação entre o Lambda e o código da sua função e um emulador de interface de runtime para testes locais.

• Usar uma imagem base somente para sistema operacional da AWS

  As imagens base somente para sistema operacional da AWS contêm uma distribuição do Amazon Linux e o emulador de interface de runtime. Essas imagens são comumente usadas para criar imagens de contêiner para linguagens compiladas, como Go e Rust e para uma linguagem ou versão de linguagem para a qual o Lambda não fornece uma imagem base, como Node.js 19. Você também pode usar imagens base somente para sistema operacional para implementar um runtime personalizado. Para tornar a imagem compatível com o Lambda, você deve incluir o cliente de interface de runtime do .NET na imagem.

• Usar uma imagem base que não é da AWS

  Você também pode usar uma imagem base alternativa de outro registro de contêiner, como Alpine Linux ou Debian. Você também pode usar uma imagem personalizada criada por sua organização. Para tornar a imagem compatível com o Lambda, você deve incluir o cliente de interface de runtime do .NET na imagem.

dica

Para reduzir o tempo necessário para que as funções do contêiner do Lambda se tornem ativas, consulte Use multi-stage builds na documentação do Docker. Para criar imagens de contêiner eficientes, siga as Melhores práticas para gravar Dockerfiles.

Esta página explica como criar, testar e implantar imagens de contêiner para o Lambda.

Imagens base da AWS para .NET

A AWS oferece as seguintes imagens base para .NET:

Tags	Runtime	Sistema operacional	Dockerfile	Desaprovação
8	.NET 8	Amazon Linux 2023	Dockerfile para .NET 8 no GitHub	Não programado
6	.NET 6	Amazon Linux 2	Dockerfile para .NET 6 no GitHub	20 de dezembro de 2024

Repositório do Amazon ECR: gallery.ecr.aws/lambda/dotnet

Usar uma imagem base da AWS para .NET

Pré-requisitos

Para executar as etapas desta seção, você deve ter o seguinte:

• .NET SDK: as etapas a seguir usam a imagem base do .NET 8. Certifique-se de que sua versão do .NET corresponda à versão da imagem base que você especifica em seu Dockerfile.

• Docker

Criação e implantação de uma imagem usando uma imagem base

Nas etapas a seguir, você usará Amazon.Lambda.Templates e Amazon.Lambda.Tools para criar um projeto.NET. Em seguida, você construirá uma imagem do Docker, fará upload da imagem no Amazon ECR e a implantará em uma função do Lambda.

1. Instale o pacote NuGet Amazon.Lambda.Templates.

   dotnet new install Amazon.Lambda.Templates

2. Crie um projeto .NET usando o modelo lambda.image.EmptyFunction.

   dotnet new lambda.image.EmptyFunction --name MyFunction --region us-east-1

3. Navegue até o diretório MyFunction/src/MyFunction. É aqui o local em que os arquivos do projeto são armazenados. Examine os seguintes arquivos:

   • aws-lambda-tools-defaults.json: este arquivo é onde você especifica as opções de linha de comando ao implantar sua função do Lambda.

   • Function.cs: o código da função do manipulador do Lambda. Ele é um modelo em C# que inclui a biblioteca Amazon.Lambda.Core padrão e um atributo LambdaSerializer padrão. Para obter mais informações sobre os requisitos e as opções de serialização, consulte Serialização em funções do Lambda. É possível usar o código fornecido para testes ou substituí-lo pelo seu.

   • MyFunction.csproj: um arquivo de projeto .NET que lista os arquivos e conjuntos que compõem sua aplicação.

   • Readme.md: este arquivo contém mais informações sobre a função do Lambda de exemplo.

4. Examine o Dockerfile no diretório src/MyFunction. É possível usar o Dockerfile fornecido para testes ou substituí-lo pelo seu. Se você usar o seu próprio, certifique-se de:

   • Definir a propriedade FROM como o URI da imagem base. Sua versão do .NET corresponda à versão da imagem base.

   • Definir o argumento CMD para o manipulador de funções do Lambda. Isso deve corresponder ao image-command em aws-lambda-tools-defaults.json.

   Observe que o Dockerfile de exemplo não inclui uma instrução USER. Quando você implanta uma imagem de contêiner no Lambda, o Lambda define automaticamente um usuário padrão do Linux com permissões de privilégio mínimo. Isso é diferente do comportamento padrão do Docker, que adota o usuário root como padrão quando nenhuma instrução USER é fornecida.

   exemplo Dockerfile

   # You can also pull these images from DockerHub amazon/aws-lambda-dotnet:8
   FROM public.ecr.aws/lambda/dotnet:8
     
   # Copy function code to Lambda-defined environment variable
   COPY publish/* ${LAMBDA_TASK_ROOT}
     
   # Set the CMD to your handler (could also be done as a parameter override outside of the Dockerfile)
   CMD [ "MyFunction::MyFunction.Function::FunctionHandler" ]

5. Instale a .NET Global Tool do Amazon.Lambda.Tools.

   dotnet tool install -g Amazon.Lambda.Tools

   Se o Amazon.Lambda.Tools já estiver instalado, certifique-se de ter a versão mais recente.

   dotnet tool update -g Amazon.Lambda.Tools

6. Altere o diretório para MyFunction/src/MyFunction, caso você ainda não esteja lá.

   cd src/MyFunction

7. Use o Amazon.Lambda.Tools para construir a imagem do Docker, enviá-la para um novo repositório do Amazon ECR e implantar a função do Lambda.

   Em --function-role, especifique o nome do perfil, não o nome do recurso da Amazon (ARN), do perfil de execução da função. Por exemplo, lambda-role.

   dotnet lambda deploy-function MyFunction --function-role lambda-role

   Para obter mais informações sobre a ferramenta do Amazon.Lambda.Tools do .NET Global, consulte o repositório AWS Extensions for .NET CLI no GitHub.

8. Invoque a função.

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

   Se tudo for bem-sucedido, você verá o seguinte:

   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

9. Exclua a função do Lambda.

   dotnet lambda delete-function MyFunction

Usar uma imagem base alternativa com o cliente da interface de runtime

Se você usar uma imagem base somente para sistema operacional ou uma imagem base alternativa, deverá incluir o cliente de interface de runtime na imagem. O cliente de interface de runtime estende Usar a API de runtime do Lambda para runtimes personalizados, que gerencia a interação entre o Lambda e o código da sua função.

O exemplo a seguir demonstra como criar uma imagem de contêiner para .NET usando uma imagem base que não é da AWS e como adicionar o pacote Amazon.Lambda.RuntimeSupport, que é o cliente da interface de runtime do Lambda para .NET. O Dockerfile do exemplo usa a imagem base do Microsoft .NET 8.

Pré-requisitos

Para executar as etapas desta seção, você deve ter o seguinte:

• .NET SDK: as etapas a seguir usam uma imagem base do .NET 8. Certifique-se de que sua versão do .NET corresponda à versão da imagem base que você especifica em seu Dockerfile.

• Docker

Criar e implantar uma imagem usando uma imagem base alternativa

1. Instale o pacote NuGet Amazon.Lambda.Templates.

   dotnet new install Amazon.Lambda.Templates

2. Crie um projeto .NET usando o modelo lambda.CustomRuntimeFunction. Esse modelo inclui o pacote Amazon.Lambda.RuntimeSupport.

   dotnet new lambda.CustomRuntimeFunction --name MyFunction --region us-east-1

3. Navegue até o diretório MyFunction/src/MyFunction. É aqui o local em que os arquivos do projeto são armazenados. Examine os seguintes arquivos:

   • aws-lambda-tools-defaults.json: este arquivo é onde você especifica as opções de linha de comando ao implantar sua função do Lambda.

   • Function.cs: o código contém uma classe com um método Main que inicializa a biblioteca Amazon.Lambda.RuntimeSupport como bootstrap. O método Main é o ponto de entrada para o processo da função. O método Main ajusta o manipulador da função em um wrappper com o qual o bootstrap pode trabalhar. Para obter mais informações, consulte Usar Amazon.Lambda.RuntimeSupport como uma biblioteca de classes no repositório do GitHub.

   • MyFunction.csproj: um arquivo de projeto .NET que lista os arquivos e conjuntos que compõem sua aplicação.

   • Readme.md: este arquivo contém mais informações sobre a função do Lambda de exemplo.

4. Abra o arquivo aws-lambda-tools-defaults.json e adicione as seguintes linhas:

     "package-type": "image",
     "docker-host-build-output-dir": "./bin/Release/lambda-publish"

   • package-type: define o pacote de implantação como uma imagem de contêiner.

   • docker-host-build-output-dir: define o diretório de saída para o processo de compilação.

   exemplo 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"
   }

5. Crie um Dockerfile no diretório MyFunction/src/MyFunction. O Dockerfile de exemplo a seguir usa uma imagem base do Microsoft.NET em vez de uma imagem base da AWS.

   • Defina a propriedade FROM como o identificador da imagem base. Sua versão do .NET corresponda à versão da imagem base.

   • Use o comando COPY para copiar a função para o diretório /var/task.

   • Defina o ENTRYPOINT como o módulo em que você deseja que o contêiner do Docker seja executado quando for iniciado. Nesse caso, o módulo é o bootstrap, que inicializa a biblioteca Amazon.Lambda.RuntimeSupport.

   Observe que o Dockerfile de exemplo não inclui uma instrução USER. Quando você implanta uma imagem de contêiner no Lambda, o Lambda define automaticamente um usuário padrão do Linux com permissões de privilégio mínimo. Isso é diferente do comportamento padrão do Docker, que adota o usuário root como padrão quando nenhuma instrução USER é fornecida.

   exemplo Dockerfile

   # You can also pull these images from DockerHub amazon/aws-lambda-dotnet:8
   FROM mcr.microsoft.com/dotnet/runtime:8.0
   
   # Set the image's internal work directory
   WORKDIR /var/task
     
   # Copy function code to Lambda-defined environment variable
   COPY "bin/Release/net8.0/linux-x64"  .
     
   # Set the entrypoint to the bootstrap
   ENTRYPOINT ["/usr/bin/dotnet", "exec", "/var/task/bootstrap.dll"]

6. Instale a extensão .NET Global Tools Amazon.Lambda.Tools.

   dotnet tool install -g Amazon.Lambda.Tools

   Se o Amazon.Lambda.Tools já estiver instalado, certifique-se de ter a versão mais recente.

   dotnet tool update -g Amazon.Lambda.Tools

7. Use o Amazon.Lambda.Tools para criar a imagem do Docker, enviá-la para um novo repositório do Amazon ECR e implantar a função do Lambda.

   Em --function-role, especifique o nome do perfil, não o nome do recurso da Amazon (ARN), do perfil de execução da função. Por exemplo, lambda-role.

   dotnet lambda deploy-function MyFunction --function-role lambda-role

   Para obter mais informações sobre a extensão da CLi Amazon.Lambda.Tools .NET, consulte o repositório AWS Extensions for .NET CLI no GitHub.

8. Invoque a função.

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

   Se tudo for bem-sucedido, você verá o seguinte:

   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

9. Exclua a função do Lambda.

   dotnet lambda delete-function MyFunction