Adaptateur Web AWS Lambda

Un outil pour exécuter des applications Web sur AWS Lambda

AWS Lambda Web Adapter permet aux développeurs de créer des applications Web (API http) avec des frameworks familiers (par exemple Express.js, Next.js, Flask, SpringBoot, ASP.NET et Laravel, tout parle HTTP 1.1/1.0) et de les exécuter sur AWS Lambda. . La même image Docker peut s'exécuter sur AWS Lambda, Amazon EC2, AWS Fargate et les ordinateurs locaux.

Adaptateur Web Lambda

Caractéristiques

Exécuter des applications Web sur AWS Lambda
Prend en charge les points de terminaison de l'API Rest Amazon API Gateway et de l'API Http, des URL de fonction Lambda et de l'équilibreur de charge d'application.
Prend en charge les environnements d'exécution gérés Lambda, les environnements d'exécution personnalisés et les images Docker OCI
Prend en charge tous les frameworks et langages Web, aucune nouvelle dépendance de code à inclure
Réponse binaire d'encodage automatique
Permet un arrêt progressif
Prend en charge la compression de la charge utile de réponse
Prend en charge le streaming de réponses
Prend en charge les déclencheurs d'événements non http

Usage

AWS Lambda Web Adapter fonctionne avec les fonctions Lambda regroupées sous forme d'images Docker et de packages Zip.

Fonctions Lambda regroupées sous forme d'images Docker ou d'images OCI

Pour utiliser Lambda Web Adaptor avec des images Docker, regroupez votre application Web (API http) dans un Dockerfile et ajoutez une ligne pour copier le binaire Lambda Web Adaptor dans /opt/extensions à l'intérieur de votre conteneur :

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

Des images de base non AWS peuvent être utilisées puisque le Runtime Interface Client est livré avec Lambda Web Adapter.

Par défaut, Lambda Web Adapter suppose que l'application Web écoute sur le port 8080. Sinon, vous pouvez spécifier le port via la configuration.

Les binaires Lambda Web Adapter précompilés sont fournis dans le dépôt public ECR : public.ecr.aws/awsguru/aws-lambda-adapter. Des images multi-arches sont également fournies dans ce référentiel. Il fonctionne sur les architectures CPU x86_64 et arm64.

Vous trouverez ci-dessous un Dockerfile pour un exemple d'application nodejs.

 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" ]

Cela fonctionne avec toutes les images de base, à l'exception des images de base gérées par AWS. Pour utiliser des images de base gérées par AWS, vous devez remplacer le ENTRYPOINT pour démarrer votre application Web.

Fonctions Lambda regroupées sous forme de package Zip pour les environnements d'exécution gérés par AWS

AWS Lambda Web Adaptor fonctionne également avec les environnements d'exécution Lambda gérés par AWS. Vous devez faire trois choses :

attachez la couche Lambda Web Adapter à votre fonction.
Régions commerciales AWS
1. x86_64 : arn:aws:lambda:${AWS::Region}:753240598075:layer:LambdaAdapterLayerX86:23
2. arm64 : arn:aws:lambda:${AWS::Region}:753240598075:layer:LambdaAdapterLayerArm64:23
Régions AWS Chine
1. cn-nord-1 (Pékin)
  - x86_64 : arn:aws-cn:lambda:cn-north-1:041581134020:layer:LambdaAdapterLayerX86:23
2. cn-nord-ouest-1 (Ningxia)
  - x86_64 : arn:aws-cn:lambda:cn-northwest-1:069767869989:layer:LambdaAdapterLayerX86:23
configurez la variable d'environnement Lambda AWS_LAMBDA_EXEC_WRAPPER sur /opt/bootstrap .
définissez le gestionnaire de fonctions sur le script de démarrage de votre application Web. par exemple run.sh .

Pour plus de détails, veuillez consulter l'exemple d'application Node.js.

Vérification de l'état de préparation

Lorsqu'un nouvel environnement d'exécution Lambda démarre, Lambda Web Adapter démarre en tant qu'extension Lambda, suivi de l'application Web.

Par défaut, Lambda Web Adaptor enverra les requêtes HTTP GET à l'application Web à l' http://127.0.0.1:8080/ . Le port et le chemin peuvent être personnalisés avec deux variables d'environnement : AWS_LWA_READINESS_CHECK_PORT et AWS_LWA_READINESS_CHECK_PATH .

Lambda Web Adapter réessayera cette demande toutes les 10 millisecondes jusqu'à ce que l'application Web renvoie une réponse HTTP ( code d'état >= 100 et < 500 ) ou jusqu'à ce que la fonction expire.

De plus, vous pouvez configurer l'adaptateur pour effectuer une vérification de préparation avec la connexion TCP, en définissant AWS_LWA_READINESS_CHECK_PROTOCOL sur tcp .

Après avoir réussi le contrôle de préparation, Lambda Web Adapter démarrera Lambda Runtime et transmettra les appels à l'application Web.

Configurations

Le port/chemin de vérification de l'état de préparation et le port de trafic peuvent être configurés à l'aide de variables d'environnement. Ces variables d'environnement peuvent être définies soit dans le fichier Docker, soit en tant que configuration de fonction Lambda.

Variable d'environnement	Description	Défaut
AWS_LWA_PORT/PORT*	port de trafic	"8080"
AWS_LWA_READINESS_CHECK_PORT / READINESS_CHECK_PORT*	port de vérification de l'état de préparation, par défaut le port de trafic	PORT
AWS_LWA_READINESS_CHECK_PATH / READINESS_CHECK_PATH*	chemin de vérification de l'état de préparation	"/"
AWS_LWA_READINESS_CHECK_PROTOCOL / READINESS_CHECK_PROTOCOL*	protocole de vérification de l'état de préparation : "http" ou "tcp", la valeur par défaut est "http"	"http"
AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS	Le code d'état HTTP minimum considéré comme non sain	"500"
AWS_LWA_ASYNC_INIT / ASYNC_INIT*	activer l'initialisation asynchrone pour les fonctions d'initialisation longues	"FAUX"
AWS_LWA_REMOVE_BASE_PATH / REMOVE_BASE_PATH*	le chemin de base à supprimer du chemin de la requête	Aucun
AWS_LWA_ENABLE_COMPRESSION	activer la compression gzip pour le corps de la réponse	"FAUX"
AWS_LWA_INVOKE_MODE	Mode d'appel de la fonction Lambda : "buffered" ou "response_stream", la valeur par défaut est "buffered"	"buffé"
AWS_LWA_PASS_THROUGH_PATH	le chemin de réception des charges utiles d'événements transmises par des déclencheurs non http	"/événements"
AWS_LWA_AUTHORIZATION_SOURCE	un nom d'en-tête à remplacer par `Authorization`	Aucun

Remarque : Nous utilisons le préfixe « AWS_LWA_ » pour espacer les noms de toutes les variables d'environnement utilisées par Lambda Web Adaptor. Les originaux seront pris en charge jusqu'à ce que nous atteignions la version 1.0.

AWS_LWA_PORT / PORT - Lambda Web Adapter enverra le trafic vers ce port. Il s'agit du port sur lequel votre application Web écoute. Dans l'environnement d'exécution Lambda, l'application Web s'exécute en tant qu'utilisateur non root et n'est pas autorisée à écouter sur les ports inférieurs à 1024. Veuillez également éviter les ports 9001 et 3000. L'API Lambda Runtime est sur le port 9001. L'extension CloudWatch Lambda Insight utilise le port 3000. .

AWS_LWA_ASYNC_INIT / ASYNC_INIT - Les environnements d'exécution gérés Lambda offrent jusqu'à 10 secondes pour l'initialisation de la fonction. Pendant cette période, les fonctions Lambda ont une explosion de CPU pour accélérer l'initialisation, et c'est gratuit. Si une fonction lambda ne parvient pas à terminer l'initialisation dans les 10 secondes, Lambda redémarrera la fonction et facturera l'initialisation. Pour aider les fonctions à utiliser ce temps d'initialisation gratuit de 10 secondes et à éviter le redémarrage, Lambda Web Adaptor prend en charge l'initialisation asynchrone. Lorsque cette fonctionnalité est activée, Lambda Web Adaptor effectue une vérification de préparation pendant 9,8 secondes maximum. Si l'application Web n'est pas prête à ce moment-là, Lambda Web Adapter signale au service Lambda que l'initialisation est terminée et poursuit la vérification de l'état de préparation dans le gestionnaire. Cette fonctionnalité est désactivée par défaut. Activez-le en définissant la variable d'environnement AWS_LWA_ASYNC_INIT sur true .

AWS_LWA_REMOVE_BASE_PATH / REMOVE_BASE_PATH - La valeur de cette variable d'environnement indique à l'adaptateur si l'application s'exécute sous un chemin de base. Par exemple, vous auriez pu configurer votre API Gateway pour avoir une ressource /orders/{proxy+} et une /catalog/{proxy+}. Chaque ressource est gérée par des fonctions Lambda distinctes. Pour cette raison, l'application dans Lambda peut ne pas être consciente du fait que le chemin /orders existe. Utilisez REMOVE_BASE_PATH pour supprimer le préfixe /orders lors du routage des demandes vers l'application. La valeur par défaut est une chaîne vide. Extrait de l'exemple SpringBoot.

AWS_LWA_ENABLE_COMPRESSION - Lambda Web Adapter prend en charge la compression gzip pour le corps de la réponse. Cette fonctionnalité est désactivée par défaut. Activez-le en définissant la variable d'environnement AWS_LWA_ENABLE_COMPRESSION sur true . Lorsqu'elle est activée, cette option compressera les réponses, sauf s'il s'agit d'une image déterminée par le type de contenu commençant par image ou si la réponse fait moins de 32 octets. Cela compressera également la réponse de streaming fragmentée HTTP/1.1.

AWS_LWA_INVOKE_MODE - Mode d'appel de fonction Lambda, cela doit correspondre au mode d'appel d'URL de fonction. La valeur par défaut est "buffé". Lorsqu'il est configuré en tant que « response_stream », Lambda Web Adapter diffuse la réponse sur le blog du service Lambda. Veuillez consulter l'exemple de FastAPI avec Response Streaming.

AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS - vous permet de personnaliser les codes d'état HTTP qui sont considérés comme sains et ceux qui ne le sont pas.

AWS_LWA_PASS_THROUGH_PATH - Chemin d'accès pour recevoir les charges utiles d'événements transmises par des déclencheurs d'événements non http. La valeur par défaut est "/events".

AWS_LWA_AUTHORIZATION_SOURCE - Lorsqu'il est défini, Lambda Web Adaptor remplace le nom d'en-tête spécifié par Authorization avant de transmettre une demande par proxy. Ceci est utile lorsque vous utilisez l'URL de la fonction Lambda avec le type d'authentification IAM, qui réserve l'en-tête d'autorisation pour l'authentification IAM, mais que vous souhaitez toujours utiliser l'en-tête d'autorisation pour vos applications backend. Cette fonctionnalité est désactivée par défaut.

Contexte de la demande

Le contexte de demande correspond aux métadonnées qu'API Gateway envoie à Lambda pour une demande. Il contient généralement requestId, requestTime, apiId, l'identité et l'autorisateur. L'identité et l'autorisateur sont utiles pour obtenir l'identité du client pour l'autorisation. Le guide du développeur API Gateway contient plus de détails ici.

Lambda Web Adapter transmet ces informations à l'application Web dans un en-tête HTTP nommé « x-amzn-request-context ». Dans l'application web, vous pouvez récupérer la valeur de cet en-tête http et le désérialiser en un objet JSON. Consultez Express.js dans Zip pour savoir comment l'utiliser.

Contexte Lambda

Lambda Context est un objet que Lambda transmet au gestionnaire de fonctions. Cet objet fournit des informations sur l'environnement d'appel, de fonction et d'exécution. Vous pouvez trouver une liste complète des propriétés accessibles via le contexte Lambda ici

Lambda Web Adapter transmet ces informations à l'application Web dans un en-tête HTTP nommé « x-amzn-lambda-context ». Dans l'application web, vous pouvez récupérer la valeur de cet en-tête http et le désérialiser en un objet JSON. Consultez Express.js dans Zip pour savoir comment l'utiliser.

Arrêt progressif

Pour une fonction avec des extensions Lambda enregistrées, Lambda active la phase d'arrêt pour la fonction. Lorsque le service Lambda est sur le point d'arrêter un environnement d'exécution Lambda, il envoie un signal SIGTERM au runtime, puis un événement SHUTDOWN à chaque extension externe enregistrée. Les développeurs pourraient capter le signal SIGTERM dans les fonctions lambda et effectuer des tâches d'arrêt en douceur. L'Express.js donne un exemple simple. Plus de détails dans ce dépôt.

Débogage local

Lambda Web Adaptor permet aux développeurs de développer des applications Web localement avec des outils et des débogueurs familiers : exécutez simplement l'application Web localement et testez-la. Si vous souhaitez simuler l'environnement Lambda Runtime localement, vous pouvez utiliser AWS SAM CLI. La commande suivante démarre un point de terminaison de passerelle API locale et simule l'environnement d'exécution du runtime Lambda.

sam local start-api

Veuillez noter que sam local démarre un émulateur d'interface d'exécution Lambda sur le port 8080. Votre application Web doit donc éviter le port 8080 si vous prévoyez d'utiliser sam local .

Déclencheurs d'événements non HTTP

L'adaptateur Web Lambda prend également en charge tous les déclencheurs d'événements non HTTP, tels que SQS, SNS, S3, DynamoDB, Kinesis, Kafka, EventBridge et Bedrock Agents. L'adaptateur transmet la charge utile de l'événement à l'application Web via la publication http vers un chemin défini par la variable d'environnement AWS_LWA_PASS_THROUGH_PATH . Par défaut, ce chemin est défini sur /events . Dès réception de la charge utile de l'événement du corps de la requête, l'application Web doit la traiter et renvoyer les résultats sous forme de réponse JSON. Veuillez consulter SQS Express.js et Bedrock Agent FastAPI dans des exemples Zip.