Adaptador web AWS Lambda

Una herramienta para ejecutar aplicaciones web en AWS Lambda

AWS Lambda Web Adapter permite a los desarrolladores crear aplicaciones web (http api) con marcos familiares (por ejemplo, Express.js, Next.js, Flask, SpringBoot, ASP.NET y Laravel, cualquier cosa habla HTTP 1.1/1.0) y ejecutarlas en AWS Lambda. . La misma imagen de Docker se puede ejecutar en AWS Lambda, Amazon EC2, AWS Fargate y computadoras locales.

Adaptador web Lambda

Características

Ejecute aplicaciones web en AWS Lambda
Admite puntos finales de API Rest API y Http API de Amazon API Gateway, URL de funciones Lambda y balanceador de carga de aplicaciones
Admite tiempos de ejecución administrados por Lambda, tiempos de ejecución personalizados e imágenes OCI de Docker
Admite cualquier marco y lenguaje web, no se debe incluir ninguna dependencia de código nuevo
Respuesta binaria de codificación automática
Permite un apagado elegante
Admite compresión de carga útil de respuesta
Admite transmisión de respuesta
Admite activadores de eventos no http

Uso

AWS Lambda Web Adaptor funciona con funciones Lambda empaquetadas como imágenes de Docker y paquetes Zip.

Funciones Lambda empaquetadas como imágenes Docker o imágenes OCI

Para usar Lambda Web Adaptor con imágenes de Docker, empaquete su aplicación web (http api) en un Dockerfile y agregue una línea para copiar el binario de Lambda Web Adaptor a /opt/extensions dentro de su contenedor:

 COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.8.4 /lambda-adapter /opt/extensions/lambda-adapter

Se pueden utilizar imágenes base que no sean de AWS, ya que Runtime Interface Client se envía con Lambda Web Adaptor.

De forma predeterminada, Lambda Web Adaptor supone que la aplicación web está escuchando en el puerto 8080. De lo contrario, puede especificar el puerto mediante la configuración.

Los archivos binarios precompilados de Lambda Web Adaptor se proporcionan en el repositorio público de ECR: public.ecr.aws/awsguru/aws-lambda-adapter. En este repositorio también se proporcionan imágenes de múltiples arcos. Funciona en arquitecturas de CPU x86_64 y arm64.

A continuación se muestra un Dockerfile para una aplicación nodejs de ejemplo.

 FROM public.ecr.aws/docker/library/node:20-slim
COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.8.4 /lambda-adapter /opt/extensions/lambda-adapter
ENV PORT=7000
WORKDIR "/var/task"
ADD src/package.json /var/task/package.json
ADD src/package-lock.json /var/task/package-lock.json
RUN npm install --omit=dev
ADD src/ /var/task
CMD [ "node" , "index.js" ]

Esto funciona con cualquier imagen base excepto las imágenes base administradas por AWS. Para utilizar imágenes base administradas por AWS, debe anular el PUNTO DE ENTRADA para iniciar su aplicación web.

Funciones Lambda empaquetadas como paquete Zip para tiempos de ejecución administrados por AWS

AWS Lambda Web Adaptor también funciona con tiempos de ejecución de Lambda administrados por AWS. Necesitas hacer tres cosas:

adjunte la capa Lambda Web Adapter a su función.
Regiones comerciales de AWS
1. x86_64: arn:aws:lambda:${AWS::Region}:753240598075:layer:LambdaAdapterLayerX86:23
2. arm64: arn:aws:lambda:${AWS::Region}:753240598075:layer:LambdaAdapterLayerArm64:23
Regiones de AWS en China
1. cn-norte-1 (Pekín)
  - x86_64: arn:aws-cn:lambda:cn-north-1:041581134020:layer:LambdaAdapterLayerX86:23
2. cn-noroeste-1 (Ningxia)
  - x86_64: arn:aws-cn:lambda:cn-northwest-1:069767869989:layer:LambdaAdapterLayerX86:23
Configure la variable de entorno Lambda AWS_LAMBDA_EXEC_WRAPPER en /opt/bootstrap .
configure el controlador de funciones en el script de inicio de su aplicación web. por ejemplo, run.sh .

Para obtener más información, consulte la aplicación Node.js de ejemplo.

Verificación de preparación

Cuando se inicia un nuevo entorno de ejecución Lambda, Lambda Web Adaptor se iniciará como una extensión Lambda, seguido de la aplicación web.

De forma predeterminada, Lambda Web Adaptor enviará solicitudes HTTP GET a la aplicación web en http://127.0.0.1:8080/ . El puerto y la ruta se pueden personalizar con dos variables de entorno: AWS_LWA_READINESS_CHECK_PORT y AWS_LWA_READINESS_CHECK_PATH .

Lambda Web Adaptor reintentará esta solicitud cada 10 milisegundos hasta que la aplicación web devuelva una respuesta HTTP ( código de estado >= 100 y < 500 ) o la función agote el tiempo de espera.

Además, puede configurar el adaptador para realizar una verificación de preparación con conexión TCP, configurando AWS_LWA_READINESS_CHECK_PROTOCOL en tcp .

Después de pasar la verificación de preparación, Lambda Web Adaptor iniciará Lambda Runtime y reenviará las invocaciones a la aplicación web.

Configuraciones

El puerto/ruta de verificación de preparación y el puerto de tráfico se pueden configurar mediante variables de entorno. Estas variables de entorno se pueden definir dentro del archivo acoplable o como configuración de la función Lambda.

Variable de entorno	Descripción	Por defecto
AWS_LWA_PORT / PUERTO*	puerto de tráfico	"8080"
AWS_LWA_READINESS_CHECK_PORT / READINESS_CHECK_PORT*	Puerto de verificación de preparación, predeterminado al puerto de tráfico.	PUERTO
AWS_LWA_READINESS_CHECK_PATH / READINESS_CHECK_PATH*	ruta de verificación de preparación	"/"
AWS_LWA_READINESS_CHECK_PROTOCOL / READINESS_CHECK_PROTOCOL*	Protocolo de verificación de preparación: "http" o "tcp", el valor predeterminado es "http"	"http"
AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS	El código de estado HTTP mínimo que se considera incorrecto	"500"
AWS_LWA_ASYNC_INIT / ASYNC_INIT*	habilitar la inicialización asincrónica para funciones de inicialización largas	"FALSO"
AWS_LWA_REMOVE_BASE_PATH / REMOVE_BASE_PATH*	la ruta base que se eliminará de la ruta de solicitud	Ninguno
AWS_LWA_ENABLE_COMPRESSION	habilitar la compresión gzip para el cuerpo de la respuesta	"FALSO"
AWS_LWA_INVOKE_MODE	Modo de invocación de función Lambda: "almacenado en búfer" o "response_stream", el valor predeterminado es "almacenado en búfer"	"amortiguado"
AWS_LWA_PASS_THROUGH_PATH	la ruta para recibir cargas útiles de eventos que se transmiten desde activadores que no son http	"/eventos"
AWS_LWA_AUTHORIZATION_SOURCE	un nombre de encabezado que se reemplazará por `Authorization`	Ninguno

Nota: Usamos el prefijo "AWS_LWA_" para asignar espacios de nombres a todas las variables de entorno utilizadas por Lambda Web Adaptor. Los originales serán compatibles hasta llegar a la versión 1.0.

AWS_LWA_PORT / PORT : Lambda Web Adaptor enviará tráfico a este puerto. Este es el puerto en el que escucha su aplicación web. Dentro del entorno de ejecución de Lambda, la aplicación web se ejecuta como un usuario no root y no se le permite escuchar en puertos inferiores a 1024. Evite también los puertos 9001 y 3000. Lambda Runtime API está en el puerto 9001. La extensión CloudWatch Lambda Insight utiliza el puerto 3000 .

AWS_LWA_ASYNC_INIT / ASYNC_INIT : los tiempos de ejecución administrados de Lambda ofrecen hasta 10 segundos para la inicialización de la función. Durante este período de tiempo, las funciones Lambda han explotado la CPU para acelerar la inicialización y es gratuita. Si una función lambda no pudo completar la inicialización en 10 segundos, Lambda reiniciará la función y facturará la inicialización. Para ayudar a las funciones a utilizar este tiempo de inicialización gratuito de 10 segundos y evitar el reinicio, Lambda Web Adaptor admite la inicialización asincrónica. Cuando esta función está habilitada, Lambda Web Adaptor realiza una verificación de preparación en hasta 9,8 segundos. Si la aplicación web no está lista para entonces, Lambda Web Adaptor indica al servicio Lambda que el inicio se completó y continúa la verificación de preparación en el controlador. Esta característica está deshabilitada de forma predeterminada. Habilítelo configurando la variable de entorno AWS_LWA_ASYNC_INIT en true .

AWS_LWA_REMOVE_BASE_PATH / REMOVE_BASE_PATH : el valor de esta variable de entorno le indica al adaptador si la aplicación se está ejecutando en una ruta base. Por ejemplo, podría haber configurado su API Gateway para tener un recurso /orders/{proxy+} y /catalog/{proxy+}. Cada recurso es manejado por funciones Lambda independientes. Por este motivo, es posible que la aplicación dentro de Lambda no sea consciente del hecho de que existe la ruta /orders. Utilice REMOVE_BASE_PATH para eliminar el prefijo /orders al enrutar solicitudes a la aplicación. El valor predeterminado es una cadena vacía. Consulte el ejemplo de SpringBoot.

AWS_LWA_ENABLE_COMPRESSION : Lambda Web Adaptor admite la compresión gzip para el cuerpo de la respuesta. Esta característica está deshabilitada de forma predeterminada. Habilítelo configurando la variable de entorno AWS_LWA_ENABLE_COMPRESSION en true . Cuando está habilitado, esto comprimirá las respuestas a menos que sea una imagen según lo determine el tipo de contenido que comienza con image o que la respuesta tenga menos de 32 bytes. Esto también comprimirá la respuesta de transmisión fragmentada de HTTP/1.1.

AWS_LWA_INVOKE_MODE : modo de invocación de función Lambda; esto debe coincidir con el modo de invocación de URL de función. El valor predeterminado es "almacenado en búfer". Cuando se configura como "response_stream", Lambda Web Adaptor transmitirá la respuesta al blog del servicio Lambda. Consulte el ejemplo de FastAPI con Response Streaming.

AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS : le permite personalizar qué códigos de estado HTTP se consideran saludables y cuáles no.

AWS_LWA_PASS_THROUGH_PATH : ruta para recibir cargas útiles de eventos transmitidas desde activadores de eventos no http. El valor predeterminado es "/eventos".

AWS_LWA_AUTHORIZATION_SOURCE : cuando se establece, Lambda Web Adaptor reemplaza el nombre del encabezado especificado por Authorization antes de enviar una solicitud. Esto es útil cuando usa la URL de la función Lambda con el tipo de autenticación de IAM, que reserva el encabezado de Autorización para la autenticación de IAM, pero aún desea usar el encabezado de Autorización para sus aplicaciones backend. Esta característica está deshabilitada de forma predeterminada.

Solicitar contexto

El contexto de solicitud son metadatos que API Gateway envía a Lambda para una solicitud. Por lo general, contiene requestId, requestTime, apiId, identidad y autorizador. La identidad y el autorizador son útiles para obtener la identidad del cliente para la autorización. La Guía para desarrolladores de API Gateway contiene más detalles aquí.

Lambda Web Adaptor reenvía esta información a la aplicación web en un encabezado Http denominado "x-amzn-request-context". En la aplicación web, puede recuperar el valor de este encabezado http y deserializarlo en un objeto JSON. Consulte Express.js en Zip para saber cómo usarlo.

Contexto lambda

Lambda Context es un objeto que Lambda pasa al controlador de funciones. Este objeto proporciona información sobre el entorno de invocación, función y ejecución. Puede encontrar una lista completa de propiedades accesibles a través de Lambda Context aquí

Lambda Web Adaptor reenvía esta información a la aplicación web en un encabezado Http denominado "x-amzn-lambda-context". En la aplicación web, puede recuperar el valor de este encabezado http y deserializarlo en un objeto JSON. Consulte Express.js en Zip para saber cómo usarlo.

Apagado elegante

Para una función con extensiones Lambda registradas, Lambda habilita la fase de apagado de la función. Cuando el servicio Lambda está a punto de cerrar un entorno de ejecución de Lambda, envía una señal SIGTERM al tiempo de ejecución y luego un evento SHUTDOWN a cada extensión externa registrada. Los desarrolladores podrían captar la señal SIGTERM en las funciones lambda y realizar tareas de apagado elegantes. Express.js ofrece un ejemplo sencillo. Más detalles en este repositorio.

Depuración local

Lambda Web Adapter permite a los desarrolladores desarrollar aplicaciones web localmente con depuradores y herramientas familiares: simplemente ejecute la aplicación web localmente y pruébela. Si desea simular el entorno Lambda Runtime localmente, puede utilizar la CLI de AWS SAM. El siguiente comando inicia un punto final de puerta de enlace de API local y simula el entorno de ejecución del tiempo de ejecución de Lambda.

sam local start-api

Tenga en cuenta que sam local inicia un emulador de interfaz Lambda Runtime en el puerto 8080. Por lo tanto, su aplicación web debe evitar el puerto 8080 si planea utilizar sam local .

Activadores de eventos no HTTP

Lambda Web Adaptor también admite todos los activadores de eventos que no sean HTTP, como SQS, SNS, S3, DynamoDB, Kinesis, Kafka, EventBridge y Bedrock Agents. El adaptador reenvía la carga útil del evento a la aplicación web a través de una publicación http a una ruta definida por la variable de entorno AWS_LWA_PASS_THROUGH_PATH . De forma predeterminada, esta ruta está configurada en /events . Al recibir la carga útil del evento del cuerpo de la solicitud, la aplicación web debe procesarla y devolver los resultados como una respuesta JSON. Consulte los ejemplos de SQS Express.js y Bedrock Agent FastAPI en Zip.