API Extensions Lambda - AWS Lambda

API Extensions Lambda

Les auteurs de fonctions Lambda utilisent des extensions pour intégrer Lambda avec leurs outils de prédilection en matière de surveillance, d’observabilité, de sécurité et de gouvernance. Les auteurs de fonctions peuvent utiliser des extensions de AWS, de partenaires AWS et de projets open-source. Pour plus d’informations sur l’utilisation des extensions, consultez l’article intitulé Introducing AWS Lambda Extensions du blog AWS Compute.


        Diagramme d’architecture de l’environnement d’exécution.

En tant qu’auteur d’extension, vous pouvez utiliser l’API d’extensions Lambda pour opérer une intégration profonde à l’environnement d’exécution Lambda. Votre extension peut enregistrer les événements du cycle de vie de la fonction et de l’environnement d’exécution. En réponse à ces événements, vous pouvez démarrer de nouveaux processus, exécuter une logique, ainsi que contrôler et orienter toutes les phases du cycle de vie Lambda : initialisation, appel et arrêt. En outre, vous pouvez utiliser l’API Runtime Logs pour recevoir un flux de journaux.

Une extension s’exécute en tant que processus indépendant dans l’environnement d’exécution et peut continuer de s’exécuter une fois l’appel de fonction entièrement traité. Étant donné que les extensions s’exécutent en tant que processus, vous pouvez les écrire dans un langage différent de celui de la fonction. Nous vous recommandons d’implémenter des extensions à l’aide d’un langage compilé. Dans ce cas, l’extension est un fichier binaire autonome compatible avec les environnements d’exécution pris en charge. Tous les Environnements d’exécution (runtimes) Lambda prennent en charge des extensions. Si vous utilisez un langage non compilé, assurez-vous d’inclure un environnement d’exécution compatible dans l’extension.

Lambda prend également en charge les extensions internes. Une extension interne s’exécute comme un thread séparé dans le processus d’exécution. L’exécution démarre et arrête l’extension interne. Un autre mode d’intégration à l’environnement Lambda consiste à utiliser des variables d’environnement spécifiques au langage et des scripts encapsuleurs. Vous pouvez utiliser ces paramètres pour configurer l’environnement d’exécution et modifier le comportement de démarrage du processus d’exécution.

Vous pouvez ajouter des extensions à une fonction de deux manières. Pour une fonction déployée en tant qu’archive de fichier .zip, vous déployez votre extension en tant que couche. Pour une fonction définie comme une image de conteneur, vous ajoutez les extensions à cette dernière.

Note

Pour des exemples d’extensions et de scripts encapsuleurs, consultez Extensions AWS Lambda sur le référentiel AWS Samples GitHub.

Cycle de vie d’un environnement d’exécution Lambda

Le cycle de vie de l’environnement d’exécution comprend les phases suivantes :

  • Init : au cours de cette phase, Lambda crée ou libère un environnement d’exécution avec les ressources configurées, télécharge le code pour la fonction et toutes les couches, initialise les extensions, initialise l’exécution et exécute le code d’initialisation de la fonction (code en dehors du gestionnaire principal). La phase Init se produit soit lors du premier appel, soit avant les appels de fonction si vous avez activé la simultanéité approvisionnée.

    La phase Init est fractionnée en trois sous-phases : Extension init, Runtime init et Function init. Ces sous-phases garantissent que toutes les extensions et l’exécution accomplissent leurs tâches de configuration avant l’exécution du code de la fonction.

  • Invoke : au cours de cette phase, Lambda appelle le gestionnaire de la fonction. Une fois l’exécution de la fonction terminée, Lambda se prépare à gérer un autre appel de fonction.

  • Shutdown: cette phase se déclenche si la fonction Lambda ne reçoit aucun appel pendant un certain temps. Au cours de la phase Shutdown, Lambda arrête l’exécution, alerte les extensions pour les laisser s’arrêter proprement, puis supprime l’environnement. Lambda envoie à chaque extension un événement Shutdown indiquant que l’environnement est sur le point d’être arrêté.

Chaque phase commence par un événement que Lambda envoie au runtime et à toutes les extensions enregistrées. L’exécution et chaque extension signalent la fin de l’opération en envoyant une requête d’API Next. Lambda bloque l’environnement d’exécution lorsque l’exécution de chaque processus est terminée, et qu’il n’y a pas d’événement en attente.

Phase d’initialisation

Au cours de la phase Extension init, chaque extension doit s’enregistrer auprès de Lambda pour recevoir des événements. Lambda utilise le nom de fichier complet de l’extension pour vérifier que la séquence d’amorçage de celle-ci est terminée. Par conséquent, chaque appel d’API Register doit inclure l’en-tête Lambda-Extension-Name avec le nom de fichier complet de l’extension.

Vous pouvez enregistrer jusqu’à 10 extensions pour une fonction. Cette limite est appliquée via l’appel d’API Register.

Après l’enregistrement de chaque extension, Lambda démarre la phase Runtime init. Le processus d’exécution appelle functionInit pour démarrer la phase Function init.

La phase Init se termine lorsque l’environnement d’exécution et chaque extension enregistrée indiquent la fin de l’opération en envoyant une demande d’API Next.

Note

Les extensions peuvent terminer leur initialisation à n’importe quel moment de la phase Init.

Phase d’appel

Lorsqu’une fonction Lambda est appelée en réponse à une requête d’API Next, Lambda envoie un événement Invoke à l’environnement d’exécution et à chaque extension enregistrée pour l’événement Invoke.

Pendant l’appel, les extensions externes s’exécutent en parallèle avec la fonction. Elles continuent également à s’exécuter après la fin de la fonction. Cela vous permet de capturer des informations de diagnostic ou d’envoyer des journaux, des métriques et des suivis à l’emplacement de votre choix.

Après réception de la réponse de fonction de l’environnement d’exécution, Lambda renvoie celle-ci au client, même si les extensions sont toujours en cours d’exécution.

La phase Invoke prend fin lorsque l’environnement d’exécution et toutes les extensions signalent qu’ils ont terminé en envoyant une demande d’API Next.

Charge utile de l’événement : l’événement envoyé à l’environnement d’exécution (et à la fonction Lambda) transporte la totalité de la requête, les en-têtes (tels que RequestId) et la charge utile. L’événement envoyé à chaque extension contient des métadonnées décrivant le contenu de l’événement. Cet événement de cycle de vie inclut le type de l’événement, l’heure à laquelle la fonction expire (deadlineMs), la requestId, l’Amazon Resource Name (ARN) de la fonction appelée et les en-têtes de suivi.

Les extensions qui souhaitent accéder au corps de l’événement de la fonction peuvent utiliser un kit SDK interne à l’environnement d’exécution qui communique avec l’extension. Les développeurs de fonctions utilisent le kit SDK interne à l’environnement d’exécution pour envoyer la charge utile à l’extension lorsque la fonction est appelée.

Voici un exemple de charge utile :

{ "eventType": "INVOKE", "deadlineMs": 676051, "requestId": "3da1f2dc-3222-475e-9205-e2e6c6318895", "invokedFunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:ExtensionTest", "tracing": { "type": "X-Amzn-Trace-Id", "value": "Root=1-5f35ae12-0c0fec141ab77a00bc047aa2;Parent=2be948a625588e32;Sampled=1" } }

Limite de durée : le paramètre d’expiration de la fonction limite la durée de la phase Invoke entière. Par exemple, si vous définissez le délai d’expiration de la fonction sur 360 secondes, la fonction et toutes les extensions doivent être terminées dans un délai de 360 secondes. Notez qu’il n’y a pas de phase post-appel indépendante. La durée correspond à la somme de tous les temps d’appel (exécution + extensions). Elle n’est calculée que lorsque l’exécution de la fonction et de toutes les extensions est terminée.

Impact sur les performances et surcharge d’extension : les extensions peuvent avoir un impact sur les performances des fonctions. En tant qu’auteur d’extension, vous contrôlez l’impact de votre extension sur les performances. Par exemple, si votre extension effectue des opérations intensives de calcul, la durée de la fonction augmente, car le code de l’extension et de votre fonction partage les mêmes ressources d’UC. En outre, si votre extension effectue des opérations importantes après la fin de l’appel de fonction, la durée de la fonction augmente, car la phase Invoke continue jusqu’à ce que toutes les extensions signalent qu’elles sont terminées.

Note

Lambda alloue une puissance de processeur proportionnelle au paramètre de mémoire de la fonction. La durée d’exécution et d’initialisation peut augmenter avec des paramètres de mémoire inférieurs, car les processus de fonction et d’extensions sont en concurrence pour les mêmes ressources de processeur. Pour réduire la durée d’exécution et d’initialisation, essayez d’augmenter le paramètre de mémoire.

Pour vous aider à déterminer l’impact sur les performances des extensions dans la phase Invoke, Lambda génère la métrique PostRuntimeExtensionsDuration. Cette métrique mesure le temps cumulé qui s’écoule entre la demande d’API Next de l’environnement d’exécution et la dernière demande d’API Next d’une extension. La métrique MaxMemoryUsed permet de mesurer l’augmentation de la mémoire utilisée. Pour de plus amples informations sur les métriques de fonction, veuillez consulter Utilisation des métriques de fonction Lambda.

Les développeurs de fonctions peuvent exécuter différentes versions de leurs fonctions côte à côte pour comprendre l’impact d’une extension spécifique. Nous recommandons aux auteurs d’extension de publier la consommation de ressources prévue de manière à aider les développeurs de fonction dans leur choix de l’extension appropriée.

Phase d’arrêt

Quand Lambda est sur le point d’arrêter l’exécution, il envoie un Shutdown à chaque extension externe enregistrée. Les extensions peuvent utiliser ce temps pour les tâches de nettoyage final. L’événement Shutdown est envoyé en réponse à une demande d’API Next.

Limite de durée : la durée maximale de la phase Shutdown dépend de la configuration des extensions enregistrées :

  • 0 ms : fonction sans extension enregistrée

  • 500 ms : fonction avec une extension interne enregistrée.

  • 2 000 ms : fonction avec une ou plusieurs extensions externes enregistrées.

Pour une fonction avec des extensions externes, Lambda réserve jusqu’à 300 ms (500 ms pour un runtime avec une extension interne) afin de permettre au processus de l’environnement d’exécution de s’arrêter proprement. Lambda alloue le reste de la limite de 2 000 ms à l’arrêt des extensions externes.

Si l’environnement d’exécution ou une extension ne répondent pas à l’événement Shutdown dans cette limite de temps, Lambda met fin au processus à l’aide d’un signal SIGKILL.

Charge utile d’événement : l’événement Shutdown contient la raison de l’arrêt et le temps restant en millisecondes.

shutdownReason contient les éléments suivants :

  • SPINDOWN – Arrêt normal

  • TIMEOUT – Limite de durée dépassée

  • ÉCHEC : condition d’erreur, telle qu’un événement out-of-memory

{ "eventType": "SHUTDOWN", "shutdownReason": "reason for shutdown", "deadlineMs": "the time and date that the function times out in Unix time milliseconds" }

Autorisations et configuration

Les extensions s’exécutent dans le même environnement d’exécution que la fonction Lambda. Les extensions partagent également des ressources avec la fonction, telles que le processeur, la mémoire et le disque de stockage /tmp. En outre, les extensions utilisent le même rôle AWS Identity and Access Management (IAM) et le même contexte de sécurité que la fonction.

Autorisations d’accès au système de fichiers et au réseau : les extensions s’exécutent dans le même espace de noms de système de fichiers et de nom de réseau que l’environnement d’exécution de la fonction. Cela signifie que les extensions doivent être compatibles avec le système d’exploitation associé. Si une extension nécessite des règles supplémentaires de trafic réseau sortant, vous devez appliquer celles-ci à la configuration de la fonction.

Note

Étant donné que le répertoire du code de la fonction est en lecture seule, les extensions ne peuvent pas modifier le code de la fonction.

Variables d’environnement : les extensions peuvent accéder aux variables d’environnement de la fonction, à l’exception des variables suivantes spécifiques au processus d’environnement d’exécution :

  • AWS_EXECUTION_ENV

  • AWS_LAMBDA_LOG_GROUP_NAME

  • AWS_LAMBDA_LOG_STREAM_NAME

  • AWS_XRAY_CONTEXT_MISSING

  • AWS_XRAY_DAEMON_ADDRESS

  • LAMBDA_RUNTIME_DIR

  • LAMBDA_TASK_ROOT

  • _AWS_XRAY_DAEMON_ADDRESS

  • _AWS_XRAY_DAEMON_PORT

  • _HANDLER

Gestion des défaillances

Échecs d’initialisation : si une extension échoue, Lambda redémarre l’environnement d’exécution pour assurer un comportement cohérent et encourager un échec rapide des extensions. En outre, pour certains clients, les extensions doivent répondre à des besoins stratégiques tels que la journalisation, la sécurité, la gouvernance et la collecte de télémétrie.

Échecs d’appel (par exemple, manque de mémoire, expiration de fonction) : les extensions partageant des ressources avec l’environnement d’exécution, elles sont affectées par l’épuisement de la mémoire. Lorsque l’environnement d’exécution échoue, toutes les extensions et l’environnement d’exécution lui-même participent à la phase Shutdown. En outre, l’environnement d’exécution est redémarré soit automatiquement dans le cadre de l’appel actuel, soit via un mécanisme de réinitialisation différée.

En cas d’échec (par exemple, dépassement de délai d’attente de fonction ou erreur d’exécution) pendant la phase Invoke, le service Lambda effectue une réinitialisation. La réinitialisation se comporte comme un événement Shutdown. Lambda commence par arrêter l’environnement d’exécution, puis envoie un événement Shutdown à chaque extension externe enregistrée. L’événement comprend le motif de l’arrêt. Si cet environnement est utilisé pour un nouvel appel, l’extension et l’environnement d’exécution sont réinitialisés dans le cadre de l’appel suivant.

Journaux d’extension : Lambda envoie la sortie de journal des extensions à CloudWatch Logs. Lambda génère également un événement de journal supplémentaire pour chaque extension pendant la phase Init. L’événement de journal enregistre le nom et la préférence d’enregistrement (événement, configuration) en cas de succès, ou la raison de l’échec le cas échéant.

Dépannage des extensions

  • Si une demande Register échoue, assurez-vous que l’en-tête Lambda-Extension-Name de l’appel d’API Register contient le nom de fichier complet de l’extension.

  • Si la demande Register échoue pour une extension interne, assurez-vous que la demande n’est pas enregistrée pour l’événement Shutdown.

Référence d’API d’extensions

La spécification OpenAPI pour l’API d’extensions version 2020-01-01 est disponible ici : extensions-api.zip

Vous pouvez extraire la valeur du point de terminaison d’API à partir de la variable d’environnement AWS_LAMBDA_RUNTIME_API. Pour envoyer une demande Register, utilisez le préfixe 2020-01-01/ avant chaque chemin d’API. Exemples :

http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/register

Enregistrement

Au cours de la phase Extension init, chaque extension doit s’enregistrer auprès de Lambda pour recevoir les événements. Lambda utilise le nom de fichier complet de l’extension pour vérifier que la séquence d’amorçage de celle-ci est terminée. Par conséquent, chaque appel d’API Register doit inclure l’en-tête Lambda-Extension-Name avec le nom de fichier complet de l’extension.

Les extensions internes sont lancées et arrêtées par le processus d’environnement d’exécution, de sorte qu’elles ne peuvent pas être enregistrées pour l’événement Shutdown.

Chemin/extension/register

MéthodePOST

En-têtes

Lambda-Extension-Name : nom de fichier complet de l’extension. Obligatoire : oui. Type : chaîne.

Paramètres de corps

events : tableau des événements pour lesquels s’enregistrer. Requis : non. Type : tableau de chaînes. Chaînes valides : INVOKE, SHUTDOWN.

En-têtes de réponse

  • Lambda-Extension-Identifier : identifiant d’agent unique généré (chaîne UUID) requis pour toutes les requêtes subséquentes.

Codes de réponse

  • 200 – Corps de la réponse contenant le nom de la fonction, la version de la fonction et le nom du gestionnaire.

  • 400 – Demande erronée.

  • 403 – Interdit

  • 500 – Erreur de conteneur. État non récupérable. L’extension doit se fermer rapidement.

Exemple de corps de la demande

{ 'events': [ 'INVOKE', 'SHUTDOWN'] }

Exemple de corps de la réponse

{ "functionName": "helloWorld", "functionVersion": "$LATEST", "handler": "lambda_function.lambda_handler" }

Suivant

Les extensions envoient une demande d’API Next pour recevoir l’événement suivant, qui peut être un événement Invoke ou un événement Shutdown. Le corps de la réponse contient la charge utile, sous la forme d’un document JSON contenant des données d’événement.

L’extension envoie une demande d’API Next pour signaler qu’elle est prête à recevoir de nouveaux événements. Il s’agit d’un appel bloquant.

Ne définissez pas de délai d’expiration sur l’appel GET, car l’extension peut être suspendue pendant un certain temps jusqu’à ce qu’il y ait un événement à retourner.

Chemin/extension/event/next

MéthodeGET

Paramètres

Lambda-Extension-Identifier : identifiant unique pour l’extension (chaîne UUID). Obligatoire : oui. Type : chaîne UUID.

En-tête de réponse

  • Lambda-Extension-Identifier : identifiant unique de l’agent (chaîne UUID).

Codes de réponse

  • 200 : réponse contenant des informations sur l’événement suivant (EventInvoke ou EventShutdown).

  • 403 – Interdit.

  • 500 – Erreur de conteneur. État non récupérable. L’extension doit se fermer rapidement.

Erreur d’initiation

L’extension utilise cette méthode pour signaler une erreur d’initialisation à Lambda. Appelez-la lorsque l’extension ne parvient pas à s’initialiser après son enregistrement. Après que Lambda a reçu l’erreur, aucun autre appel d’API n’aboutit. L’extension doit quitter après avoir reçu la réponse de Lambda.

Chemin/extension/init/error

MéthodePOST

En-têtes

Lambda-Extension-Identifier : identifiant unique pour l’extension. Obligatoire : oui. Type : chaîne UUID.

Lambda-Extension-Function-Error-Type – Type d’erreur rencontré par l’extension. Obligatoire : oui.

Cet en-tête se compose d’une valeur de chaîne. Lambda accepte n’importe quelle chaîne, mais nous recommandons le format <category.reason>. Par exemple :

  • Extension.NoSuchHandler

  • Extension.APIKeyNotFound

  • Extension.ConfigInvalid

  • Extension.UnknownReason

Paramètres de corps

ErrorRequest : informations sur l’erreur. Requis : non.

Ce champ est un objet JSON avec la structure suivante :

{ errorMessage: string (text description of the error), errorType: string, stackTrace: array of strings }

Notez que Lambda accepte n’importe quelle valeur pour errorType.

L’exemple suivant montre un message d’erreur de fonction Lambda indiquant que la fonction n’a pas pu analyser les données d’événement fournies dans l’appel.

Exemple Erreur de fonction

{ "errorMessage" : "Error parsing event data.", "errorType" : "InvalidEventDataException", "stackTrace": [ ] }

Corps de la réponse

  • Lambda-Extension-Identifier : identifiant unique de l’agent (chaîne UUID).

Codes de réponse

  • 202 – Accepté

  • 400 – Demande erronée.

  • 403 – Interdit

  • 500 – Erreur de conteneur. État non récupérable. L’extension doit se fermer rapidement.

Erreur de sortie

L’extension utilise cette méthode pour signaler une erreur à Lambda avant de quitter. Appelez-la lorsque vous rencontrez une défaillance inattendue. Après que Lambda a reçu l’erreur, aucun autre appel d’API n’aboutit. L’extension doit quitter après avoir reçu la réponse de Lambda.

Chemin/extension/exit/error

MéthodePOST

En-têtes

Lambda-Extension-Identifier : identifiant unique pour l’extension. Obligatoire : oui. Type : chaîne UUID.

Lambda-Extension-Function-Error-Type – Type d’erreur rencontré par l’extension. Obligatoire : oui.

Cet en-tête se compose d’une valeur de chaîne. Lambda accepte n’importe quelle chaîne, mais nous recommandons le format <category.reason>. Par exemple :

  • Extension.NoSuchHandler

  • Extension.APIKeyNotFound

  • Extension.ConfigInvalid

  • Extension.UnknownReason

Paramètres de corps

ErrorRequest : informations sur l’erreur. Requis : non.

Ce champ est un objet JSON avec la structure suivante :

{ errorMessage: string (text description of the error), errorType: string, stackTrace: array of strings }

Notez que Lambda accepte n’importe quelle valeur pour errorType.

L’exemple suivant montre un message d’erreur de fonction Lambda indiquant que la fonction n’a pas pu analyser les données d’événement fournies dans l’appel.

Exemple Erreur de fonction

{ "errorMessage" : "Error parsing event data.", "errorType" : "InvalidEventDataException", "stackTrace": [ ] }

Corps de la réponse

  • Lambda-Extension-Identifier : identifiant unique de l’agent (chaîne UUID).

Codes de réponse

  • 202 – Accepté

  • 400 – Demande erronée.

  • 403 – Interdit

  • 500 – Erreur de conteneur. État non récupérable. L’extension doit se fermer rapidement.