Lambda API de extensiones - AWS Lambda

Lambda API de extensiones

Los autores de funciones de Lambda utilizan extensiones para integrar Lambda con sus herramientas preferidas de monitoreo, observabilidad, seguridad y gobernanza. Los autores de funciones pueden usar extensiones de AWS, de socios de AWS y proyectos de código abierto. Para obtener más información, consulte Introducción de extensiones de AWS Lambda en el blog de informática de AWS.

Como autor de extensiones, puede usar la API de extensiones de Lambda para integrar profundamente en el entorno de ejecución de Lambda. Su extensión puede registrarse para eventos de ciclo de vida del entorno de ejecución y función. En respuesta a estos eventos, puede iniciar nuevos procesos, ejecutar lógica, controlar y participar en todas las fases del ciclo de vida de Lambda: inicialización, invocación y apagado. Además, puede utilizar la API de registros de tiempo de ejecución para recibir una secuencia de registros.

Una extensión se ejecuta como un proceso independiente en el entorno de ejecución y puede continuar ejecutándose luego de que la invocación de la función se procese completamente. Debido a que las extensiones se ejecutan como procesos, se pueden escribir en un lenguaje diferente al de la función. Recomendamos al usuario que implemente extensiones mediante un lenguaje compilado. En este caso, la extensión es un binario autónomo compatible con todos los tiempos de ejecución admitidos. Si utiliza un lenguaje no compilado, asegúrese de incluir un tiempo de ejecución compatible en la extensión.

Los siguientes tiempos de ejecución de Lambda admiten extensiones externas:

  • .NET Core 3.1 (C#/PowerShell) (dotnetcore3.1)

  • Tiempo de ejecución personalizado (provided)

  • Tiempo de ejecución personalizado en Amazon Linux 2 (provided.al2)

  • Java 11 (Corretto) (java11)

  • Java 8 (Corretto) (java8.al2)

  • Node.js 14.x (nodejs14.x)

  • Node.js 12.x (nodejs12.x)

  • Node.js 10.x (nodejs10.x)

  • Python 3.8 (python3.8)

  • Python 3.7 (python3.7)

  • Ruby 2.7 (ruby2.7)

  • Ruby 2.5 (ruby2.5)

Lambda también es compatible con extensiones internas. Una extensión interna se ejecuta como un subproceso independiente en el proceso de tiempo de ejecución. El tiempo de ejecución inicia y detiene la extensión interna. Una forma alternativa de integrarse con el entorno de Lambda es utilizar variables de entorno específicas del lenguaje y scripts envolventes. Puede usarlas para configurar el entorno de tiempo de ejecución y modificar el comportamiento de inicio del proceso de tiempo de ejecución.

Puede agregar extensiones a una función de dos maneras. Para una función implementada como un archivo .zip, debe implementar la extensión como una capa. Para una función definida como una imagen de contenedor, se agregan las extensiones a la imagen de contenedor.

nota

Para obtener, por ejemplo, extensiones y secuencias de comandos de envoltura, consulte Extensiones AWS Lambda en el repositorio de AWS Samples GitHub.

Ciclo de vida del entorno de ejecución de Lambda

El ciclo de vida del entorno de ejecución incluye las siguientes fases:

  • Init: en esta fase, Lambda crea o desbloquea un entorno de ejecución con los recursos configurados, descarga el código para la función y todas las capas, inicializa cualquier extensión, inicializa el tiempo de ejecución y, a continuación, ejecuta el código de inicialización de la función (es decir, el código fuera del controlador principal). La fase Init ocurre durante la primera invocación o antes de las invocaciones de la función si ha habilitado la simultaneidad aprovisionada.

    La fase Init se divide en tres subfases: Extension init, Runtime init y Function init. Estas subfases garantizan que todas las extensiones y el tiempo de ejecución completan sus tareas de configuración antes de que se ejecute el código de función.

  • Invoke: en esta fase, Lambda invoca el controlador de funciones. Una vez que la función se ejecute por completo, Lambda se prepara para gestionar otra invocación de función.

  • Shutdown: esta fase se desencadena si la función Lambda no recibe ninguna invocación durante un periodo de tiempo. En la fase Shutdown, Lambda termina el tiempo de ejecución, alerta a las extensiones para que se detengan de forma correcta y, a continuación, elimina el entorno. Lambda envía un evento Shutdown a cada extensión, que le dice a la extensión que el entorno está a punto de cerrarse.

Cada fase comienza con un evento desde Lambda hasta el tiempo de ejecución y en todas las extensiones registradas. El tiempo de ejecución y cada extensión indican la finalización mediante el envío de una solicitud Next a la API. Lambda congela el entorno de ejecución cuando cada proceso se ha completado y no hay eventos pendientes.

Fase "init"

Durante la fase Extension init, cada extensión debe registrarse con Lambda para recibir eventos. Lambda utiliza el nombre de archivo completo de la extensión para validar que la extensión ha completado la secuencia de arranque. Por lo tanto, cada llamada Register a la API debe incluir el encabezado Lambda-Extension-Name con el nombre de archivo completo de la extensión.

Puede registrar hasta 10 extensiones para una función. Este límite se aplica a través de la llamada Register a la API.

Después de que cada extensión se registre, Lambda comienza la fase Runtime init. El proceso en tiempo de ejecución llama functionInit para iniciar la fase Function init.

La fase Init se completa después del tiempo de ejecución y cada extensión registrada indica la finalización mediante el envío de una solicitud Next a la API.

nota

Las extensiones pueden completar su inicialización en cualquier punto de la fase Init.

Fase "invoke"

Cuando se invoca una función Lambda en respuesta a una solicitud Next a la API, Lambda envía un evento Invoke al tiempo de ejecución y a cada extensión registrada para el evento Invoke.

Durante la invocación, las extensiones externas se ejecutan en paralelo a la función. También continúan ejecutándose después de que la función se haya completado. Esto permite al usuario capturar información de diagnóstico o enviar registros, métricas y rastros a una ubicación de su elección.

Después de recibir la respuesta de la función desde el tiempo de ejecución, Lambda devuelve la respuesta al cliente, incluso si las extensiones todavía se ejecutan.

La fase Invoke finaliza después de que el tiempo de ejecución y todas las extensiones indiquen que se han terminado mediante el envío de una solicitud Next a la API.

Carga útil del evento: el evento enviado al tiempo de ejecución (y a la función Lambda) lleva toda la solicitud, encabezados (como RequestId) y carga útil. El evento enviado a cada extensión contiene metadatos que describen el contenido del evento. Este evento de ciclo de vida incluye el tipo del evento, el tiempo de espera de la función (deadlineMs), el requestId, el nombre de recurso de Amazon (ARN) de la función invocada y los encabezados de seguimiento.

Las extensiones que desean acceder al cuerpo del evento de función pueden usar un SDK en tiempo de ejecución que se comunica con la extensión. Los desarrolladores de funciones utilizan el SDK en tiempo de ejecución para enviar la carga a la extensión cuando se invoca la función.

A continuación, se muestra un ejemplo de carga:

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

Límite de duración: la configuración de tiempo de espera de la función limita la duración de la fase Invoke al completo. Por ejemplo, si establece el tiempo de espera de la función en 360 segundos, la función y todas las extensiones deben completarse en 360 segundos. Tenga en cuenta que no hay una fase posterior a "invoke" independiente. La duración es la suma de todo el tiempo de invocación (tiempo de ejecución + extensiones) y no se calcula hasta que la función y todas las extensiones hayan terminado de ejecutarse.

Impacto de desempeño y sobrecarga de extensiones: las extensiones pueden afectar al rendimiento de la función. Como autor de la extensión, tiene control sobre el impacto de desempeño de la extensión. Por ejemplo, si la extensión realiza operaciones de procesamiento intensivo, la duración de la función aumentará porque la extensión y el código de la función comparten los mismos recursos de la CPU. Además, si la extensión realiza numerosas operaciones después de completar la invocación de la función, la duración de la ejecución de la función aumentará porque la fase Invoke continuará hasta que todas las extensiones indiquen que se han completado.

nota

Lambda asigna la potencia de la CPU en proporción a la configuración de memoria de la función. Es posible que vea una mayor duración de ejecución e inicialización en configuraciones de memoria más bajas porque los procesos de función y extensión compiten por los mismos recursos de la CPU. Para reducir la duración de ejecución e inicialización, intente aumentar la configuración de memoria.

Para ayudar a identificar el impacto del rendimiento introducido por las extensiones de la fase Invoke, Lambda genera la métrica PostRuntimeExecutionDuration. Esta métrica mide el tiempo acumulado invertido entre la solicitud Next a la API de tiempo de ejecución y la última solicitud Next a la API de la extensión. Para medir el aumento de memoria utilizada, utilice la métrica MaxMemoryUsed. Para obtener más información acerca de las métricas de función, consulte Trabajar con métricas de funciones de AWS Lambda.

Los desarrolladores de funciones pueden ejecutar diferentes versiones de sus funciones en paralelo para conocer el impacto de una extensión específica. Recomendamos que los autores de extensiones publiquen el consumo de recursos esperado para facilitar a los desarrolladores de funciones la elección de una extensión adecuada.

Fase "shutdown"

Cuando Lambda está a punto de terminar el tiempo de ejecución, envía un evento Shutdown al tiempo de ejecución y, a continuación, a cada extensión externa registrada. Las extensiones pueden utilizar este tiempo para las tareas de limpieza finales. El evento Shutdown se envía en respuesta a una solicitud Next a la API.

Límite de duración: la duración máxima de la fase Shutdown depende de la configuración de las extensiones registradas:

  • 300 ms – una función sin extensiones registradas

  • 500 ms – una función con una extensión interna registrada.

  • 2000 ms – una función con una o más extensiones externas registradas.

Para una función con extensiones externas, Lambda reserva hasta 300 ms (500 ms para un tiempo de ejecución con una extensión interna) para que el proceso de tiempo de ejecución realice un apagado estable. Lambda asigna el resto del límite de 2,000 ms para que las extensiones externas se cierren.

Si el tiempo de ejecución o una extensión no responde al evento Shutdown dentro del límite, Lambda termina el proceso mediante una señal SIGKILL.

Carga del evento: el evento Shutdown contiene el motivo del apagado y el tiempo restante en milisegundos.

shutdownReason incluye los valores que se muestran a continuación:

  • SPINDOWN: apagado normal

  • TIMEOUT: tiempo de espera límite de duración

  • FAILURE: condición de error, como un evento de out-of-memory

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

Permisos y configuración

Las extensiones se ejecutan en el mismo entorno de ejecución que la función Lambda. Las extensiones también comparten recursos con la función, como CPU, memoria y almacenamiento en disco /tmp. Además, las extensiones utilizan el mismo rol de AWS Identity and Access Management (IAM) y el mismo contexto de seguridad que la función.

Permisos de acceso al sistema de archivos y a la red: las extensiones se ejecutan en el mismo espacio de nombres de sistema de archivos y nombre de red que el tiempo de ejecución de la función. Esto significa que las extensiones deben ser compatibles con el sistema operativo asociado. Si una extensión requiere reglas de tráfico de salida de red adicionales, se deben aplicar estas reglas a la configuración de la función.

nota

Debido a que el directorio de código de función es de solo lectura, las extensiones no pueden modificar el código de función.

Variables de entorno: las extensiones pueden acceder a las variables de entorno de la función, excepto las siguientes variables que son específicas del proceso de tiempo de ejecución:

  • 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

Administración de errores

Errores de inicialización: si se produce un error en una extensión, Lambda reinicia el entorno de ejecución para imponer un comportamiento consistente y fomentar el error rápido para las extensiones. Además, para algunos clientes, las extensiones deben satisfacer necesidades críticas como registro, seguridad, gobierno y recopilación de telemetría.

Errores de Invoke (como la falta de memoria, el tiempo de espera de la función): dado que las extensiones comparten recursos con el tiempo de ejecución, el agotamiento de la memoria los afecta. Cuando el tiempo de ejecución produce un error, todas las extensiones y el propio tiempo de ejecución participan en la fase Shutdown. Además, el tiempo de ejecución se reinicia— automáticamente como parte de la invocación actual o a través de un mecanismo de reinicialización diferido.

Si hay un error (como un tiempo de espera de función o un error de tiempo de ejecución) durante Invoke, el servicio de Lambda realiza un restablecimiento. El restablecimiento se comporta como un evento Shutdown. Primero, Lambda apaga el tiempo de ejecución, luego envía un evento Shutdown a cada extensión externa registrada. El evento incluye el motivo del apagado. Si este entorno se utiliza para una nueva invocación, la extensión y el tiempo de ejecución se vuelven a inicializar como parte de la siguiente invocación.

Registros de extensión: Lambda envía la salida del registro de las extensiones a CloudWatch Logs. Lambda también genera un evento de registro adicional para cada extensión durante Init. El evento de registro registra el nombre y la preferencia de registro ("event", "config") en caso de éxito o el motivo del error en caso de error.

Extensiones de solución de problemas

  • Si se produce un error en una solicitud Register, asegúrese de que el encabezado de Lambda-Extension-Name de la llamada Register a la API contiene el nombre de archivo completo de la extensión.

  • Si la solicitud de Register produce un error para una extensión interna, asegúrese de que la solicitud no se registra para el evento Shutdown.

Referencia de la API de extensiones

La especificación de OpenAPI para la versión de la API de extensiones 2020-01-01 está disponible aquí: extensions-api.zip

Puede recuperar el valor del punto de enlace de la API desde la variable de entorno de AWS_LAMBDA_RUNTIME_API. Para enviar una solicitud de Register, utilice el prefijo 2020-01-01/ antes de cada ruta de la API. Por ejemplo:

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

Registrar

Durante Extension init, todas las extensiones deben registrarse con Lambda para recibir eventos. Lambda utiliza el nombre de archivo completo de la extensión para validar que la extensión ha completado la secuencia de arranque. Por lo tanto, cada llamada Register a la API debe incluir el encabezado Lambda-Extension-Name con el nombre de archivo completo de la extensión.

Las extensiones internas comienzan y paran según el proceso de tiempo de ejecución, por lo que no se les permite registrarse para el evento Shutdown.

Ruta: /extension/register

Método: POST

Encabezados

Lambda-Extension-Name: el nombre de archivo completo de la extensión. Requerido: sí. Tipo: cadena.

Body parameters (Parámetros del cuerpo)

events: matriz de los eventos para registrarse. Necesario: no. Tipo: matriz de cadenas. Cadenas válidas: INVOKE y SHUTDOWN.

Encabezados de respuesta

  • Lambda-Extension-Identifier: identificador de agente único generado (cadena UUID) que se requiere para todas las solicitudes posteriores.

Códigos de respuesta

  • 200: el cuerpo de la respuesta contiene el nombre de la función, la versión de la función y el nombre del controlador.

  • 400: solicitud maligna

  • 403: prohibido

  • 500: error en contenedor. Estado no recuperable. La extensión debe salir rápidamente.

ejemplo Ejemplo de cuerpo de solicitud

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

ejemplo Ejemplo de cuerpo de respuesta

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

Siguiente

Las extensiones envían una solicitud Next a la API para recibir el siguiente evento, que puede ser un evento Invoke o un evento Shutdown. El cuerpo de la respuesta contiene la carga, que es un documento JSON que contiene datos de eventos.

La extensión envía una solicitud Next a la API para indicar que está lista para recibir nuevos eventos. Esta es una llamada de bloqueo.

No establezca un tiempo de espera en la llamada GET, ya que la extensión puede suspenderse durante un periodo de tiempo hasta que haya un evento que devolver.

Ruta: /extension/event/next

Método: GET

Parámetros

Lambda-Extension-Identifier: identificador único para la extensión (cadena UUID). Requerido: sí. Tipo: cadena UUID.

Encabezado de respuesta

  • Lambda-Extension-Identifier: identificador del agente único (cadena UUID).

Códigos de respuesta

  • 200: la respuesta contiene información sobre el próximo evento (EventInvoke o EventShutdown).

  • 403: prohibido

  • 500: error en contenedor. Estado no recuperable. La extensión debe salir rápidamente.

Error de init

La extensión utiliza este método para informar de un error de inicialización en Lambda. Llámelo cuando la extensión produce un error al inicializarse después de que se haya registrado. Después de que Lambda reciba el error, no hay más llamadas a la API correctas. La extensión debe cerrarse después de recibir la respuesta de Lambda.

Ruta: /extension/init/error

Método: POST

Encabezados

Lambda-Extension-Identifier: identificador único para la extensión. Requerido: sí. Tipo: cadena UUID.

Lambda-Extension-Function-Error-Type:– tipo de error que encontró la extensión. Requerido: sí.

Este encabezado consta de un valor de cadena. Lambda acepta cualquier cadena, pero recomendamos un formato de <category.reason>. Por ejemplo:

  • Runtime.NoSuchHandler

  • Extension.APIKeyNotFound

  • Extension.ConfigInvalid

  • Extension.UnknownReason

Body parameters (Parámetros del cuerpo)

ErrorRequest:– información sobre el error. Obligatorio: no

Este campo es un objeto JSON con la siguiente estructura:

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

Tenga en cuenta que Lambda acepta cualquier valor para errorType.

En el ejemplo siguiente, se muestra un mensaje de error de función Lambda en el que la función no pudo analizar los datos de evento proporcionados en la invocación.

ejemplo Error de la función

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

Cuerpo de respuesta

  • Lambda-Extension-Identifier: identificador del agente único (cadena UUID).

Códigos de respuesta

  • 202: aceptada

  • 400: solicitud maligna

  • 403: prohibido

  • 500: error en contenedor. Estado no recuperable. La extensión debe salir rápidamente.

Error de salida

La extensión utiliza este método para informar de un error en Lambda antes de salir. Llámelo cuando encuentre un error inesperado. Después de que Lambda reciba el error, no hay más llamadas a la API correctas. La extensión debe cerrarse después de recibir la respuesta de Lambda.

Ruta: /extension/exit/error

Método: POST

Encabezados

Lambda-Extension-Identifier: identificador único para la extensión. Requerido: sí. Tipo: cadena UUID.

Lambda-Extension-Function-Error-Type:– tipo de error que encontró la extensión. Requerido: sí.

Este encabezado consta de un valor de cadena. Lambda acepta cualquier cadena, pero recomendamos un formato de <category.reason>. Por ejemplo:

  • Runtime.NoSuchHandler

  • Extension.APIKeyNotFound

  • Extension.ConfigInvalid

  • Extension.UnknownReason

Body parameters (Parámetros del cuerpo)

ErrorRequest:– información sobre el error. Obligatorio: no

Este campo es un objeto JSON con la siguiente estructura:

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

Tenga en cuenta que Lambda acepta cualquier valor para errorType.

En el ejemplo siguiente, se muestra un mensaje de error de función Lambda en el que la función no pudo analizar los datos de evento proporcionados en la invocación.

ejemplo Error de la función

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

Cuerpo de respuesta

  • Lambda-Extension-Identifier: identificador del agente único (cadena UUID).

Códigos de respuesta

  • 202: aceptada

  • 400: solicitud maligna

  • 403: prohibido

  • 500: error en contenedor. Estado no recuperable. La extensión debe salir rápidamente.