Utilice la API de las extensiones de Lambda para crear extensiones - AWS Lambda
Ciclo de vida del entorno de ejecución de LambdaReferencia de la API de extensiones

Utilice la API de las extensiones de Lambda para crear 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 utilizar extensiones de AWS o 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. En esta sección, se describe cómo utilizar la API de extensiones de Lambda, el ciclo de vida del entorno de ejecución de Lambda y la referencia de la API de extensiones de Lambda.

La API de extensiones y la API de telemetría se conectan a Lambda y a las extensiones externas.

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 los tiempos de ejecución admitidos. Todas las extensiones de soporte de Tiempos de ejecución de Lambda. Si utiliza un lenguaje no compilado, asegúrese de incluir un tiempo de ejecución compatible en la extensión.

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: durante esta fase, Lambda crea o descongela un entorno de ejecución con los recursos que ha configurado, descarga el código de función y todas las capas, inicializa las extensiones, inicializa el tiempo de ejecución y ejecuta el código de inicialización de la función (el código fuera del controlador principal). La fase Init ocurre durante la primera invocación, o antes de las invocaciones de función si ha habilitado simultanidad 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 completen 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. Después de que la función se ejecuta hasta su finalización, Lambda se prepara para manejar otra invocación de función.

  • Shutdown: esta fase se activa si la función Lambda no recibe ninguna invocación durante un período de tiempo. En la fase Shutdown, Lambda apaga el tiempo de ejecución, alerta a las extensiones para que se detengan limpiamente y, a continuación, elimina el entorno. Lambda envía un evento Shutdown a cada extensión, lo que indica 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 la finalización de cada señal de extensión mediante el envío de un solicitud de API de Next. Lambda congela el entorno de ejecución cuando cada proceso se ha completado y no hay eventos pendientes.

Ciclo de vida del entorno de ejecución de Lambda para extensiones

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.

Secuencia de eventos en la fase “Init” de Lambda

Fase "invoke"

Cuando se invoca una función de Lambda en respuesta a una solicitud a la API Next, 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.

Secuencia de eventos en la fase “Invoke” de Lambda

Carga útil del evento: el evento enviado al tiempo de ejecución (y a la función de 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 el tiempo total que tarda su tiempo de ejecución y todas las invocaciones de sus extensiones en completarse 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 PostRuntimeExtensionsDuration. 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 Uso de métricas de CloudWatch con 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 cerrar el tiempo de ejecución, envía Shutdown 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:

  • 0 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 2000 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.

Secuencia de eventos en la fase “Shutdown” de Lambda

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 de 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.

Ejemplo de entorno de ejecución: Init, Invoke, Invoke with Error, Invoke, Shutdown

Para obtener una explicación más detallada del diagrama anterior, consulte Errores durante la fase Invoke.

Registros de extensión: Lambda envía la salida de 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

Regístrese

Durante Extension init, todas las extensiones deben registrarse en 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 de solicitudes

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

  • Lambda-Extension-Accept-Feature: utilice esta opción para especificar las funciones opcionales de las extensiones durante el registro. Obligatorio: no Tipo: cadena separada por comas. Funciones disponibles para especificar mediante esta configuración:

    • accountId: si se especifica, la respuesta de registro de la extensión contendrá el ID de cuenta asociado a la función de Lambda para la que está registrando la extensión.

Parámetros del cuerpo de la solicitud

  • events: matriz de los eventos para registrarse. Obligatorio: 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 errónea

  • 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"
}
ejemplo Ejemplo de cuerpo de respuesta con función accountID opcional
{
    "functionName": "helloWorld",
    "functionVersion": "$LATEST",
    "handler": "lambda_function.lambda_handler",
    "accountId": "123456789012"
}

Next

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

Encabezados de solicitudes

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

Encabezados de respuesta

  • Lambda-Extension-Event-Identifier: identificador único para el evento (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 de solicitudes

  • 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:

    • Extension.NoSuchHandler

    • Extension.APIKeyNotFound

    • Extension.ConfigInvalid

    • Extension.UnknownReason

Parámetros del cuerpo de la solicitud

  • 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 de 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": [ ]
}
Códigos de respuesta

  • 202: aceptada

  • 400: solicitud errónea

  • 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 de solicitudes

  • 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:

    • Extension.NoSuchHandler

    • Extension.APIKeyNotFound

    • Extension.ConfigInvalid

    • Extension.UnknownReason

Parámetros del cuerpo de la solicitud

  • 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 de 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": [ ]
}
Códigos de respuesta

  • 202: aceptada

  • 400: solicitud errónea

  • 403: prohibido

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