Utilisation des extensions Lambda API pour créer des extensions

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 issues de AWS projets open source, de AWS partenaires et de projets open source. Pour plus d'informations sur l'utilisation des extensions, consultez la section Présentation des AWS Lambda extensions sur le blog AWS Compute. Cette section décrit comment utiliser les extensions LambdaAPI, le cycle de vie de l'environnement d'exécution Lambda et la référence des extensions Lambda. API

En tant qu'auteur d'extensions, vous pouvez utiliser les extensions Lambda API pour vous intégrer en profondeur dans 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 les journaux d'exécution API 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.

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

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

Chaque phase commence par un événement que Lambda envoie au runtime et à toutes les extensions enregistrées. Le runtime et chaque extension signalent l'achèvement en envoyant une Next API demande. 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 Register API appel doit inclure l'Lambda-Extension-Nameen-tête avec le nom de fichier complet de l'extension.

Vous pouvez enregistrer jusqu’à 10 extensions pour une fonction. Cette limite est appliquée par le biais de l'RegisterAPIappel.

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 Init phase se termine après l'exécution et chaque extension enregistrée indique qu'elle est terminée en envoyant une Next API demande.

Phase d’invocation

Lorsqu'une fonction Lambda est invoquée en réponse à une Next API demande, Lambda envoie un Invoke événement au moteur 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 Invoke phase se termine après l'exécution et toutes les extensions signalent qu'elles sont terminées en envoyant une Next API demande.

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 du cycle de vie inclut le type d'événement, l'heure d'expiration de la fonction (deadlineMs)requestId, le Amazon Resource Name (ARN) de la fonction invoqué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 environnement d'exécution SDK qui communique avec l'extension. Les développeurs de fonctions utilisent la fonction en cours d'exécution SDK pour envoyer la charge utile à l'extension lorsque la fonction est invoqué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-invocation indépendante. La durée est le temps total nécessaire à votre exécution et à toutes les invocations de vos extensions. Elle n'est calculée que lorsque la fonction et toutes les extensions sont terminées.

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 de calcul intensives, la durée de la fonction augmente car l'extension et le code de fonction partagent les mêmes CPU ressources. 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.

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é passé entre la Next API demande d'exécution et la dernière Next API demande d'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 Afficher les métriques des fonctions 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'Shutdownévénement est envoyé en réponse à une Next API demande.

Limite de durée : la durée maximale de la phase Shutdown dépend de la configuration des extensions 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 :

{ 
  "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 fonctionCPU, telles que la mémoire et le stockage /tmp sur disque. De plus, 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.

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 :

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.

Pour une explication plus détaillée du diagramme précédent, consultez Échecs pendant la phase d’invocation.

Journaux des extensions : Lambda envoie le résultat du 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

APIRéférence des extensions

La API spécification Open pour la API version 2020-01-01 des extensions est disponible ici : extensions-api.zip

Vous pouvez récupérer la valeur du API point de terminaison à partir de la variable d'AWS_LAMBDA_RUNTIME_APIenvironnement. Pour envoyer une Register demande, utilisez le préfixe 2020-01-01/ avant chaque API chemin. Par exemple :

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 Register API appel doit inclure l'Lambda-Extension-Nameen-tête 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éthode — POST

En-têtes de demandes

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

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

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

Suivant

Les extensions envoient une Next API demande pour recevoir le prochain événement, qui peut être un Invoke événement ou un Shutdown événement. Le corps de la réponse contient la charge utile, qui est un JSON document contenant des données d'événements.

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

Ne fixez pas de délai d'attente pour l'GETappel, car la prolongation peut être suspendue pendant un certain temps jusqu'à ce qu'un événement revienne.

Chemin – /extension/event/next

Méthode — GET

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. Une fois que Lambda a reçu l'erreur, aucun autre API appel ne réussit. L’extension doit quitter après avoir reçu la réponse de Lambda.

Chemin – /extension/init/error

Méthode — POST

Ce champ est un JSON objet dont la structure est la 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’invocation.

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

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. Une fois que Lambda a reçu l'erreur, aucun autre API appel ne réussit. L’extension doit quitter après avoir reçu la réponse de Lambda.

Chemin – /extension/exit/error

Méthode — POST

Ce champ est un JSON objet dont la structure est la 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’invocation.

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