Utilizzo dell'API Extensions di Lambda per creare estensioni

Gli autori di Lambda Event Function utilizzano le estensioni per integrare Lambda con i loro strumenti preferiti per il monitoraggio, l'osservabilità, la sicurezza e la governance. Gli autori di Event Function possono utilizzare estensioni di AWS, AWS partner e progetti open source. Per ulteriori informazioni sull'utilizzo delle estensioni, consulta Introducing AWS Lambda Extensions on the AWS Compute Blog. In questa sezione viene descritto come utilizzare l'API di estensione Lambda, il ciclo di vita dell'ambiente di esecuzione Lambda e la documentazione di riferimento delle API di estensione Lambda.

In qualità di autore dell'estensione, l'utente utilizzare l'API estensioni per ottenere un'integrazione profonda nell'ambiente di esecuzione Lambda. L'estensione può registrarsi per gli eventi del ciclo di vita di Event Function e Execution Environment. In risposta a questi eventi, è possibile avviare nuovi processi, eseguire la logica e controllare e partecipare a tutte le fasi del ciclo di vita di Lambda: inizializzazione, invocazione e arresto. Inoltre, è possibile utilizzare l'API Log di runtime per ricevere un flusso di log.

Un'estensione viene eseguita come processo indipendente nell'ambiente di esecuzione e può continuare a essere eseguita dopo l'elaborazione completa della chiamata di Event Function. Poiché le estensioni vengono eseguite come processi, è possibile scriverle in un linguaggio diverso dalla Event Function. Si consiglia di implementare le estensioni utilizzando un linguaggio compilato.

In questo caso, l'estensione è un binario autonomo compatibile con tutti i tempi di esecuzione supportati. Tutti i Runtime della funzione evento Lambda supportano le estensioni. Se si utilizza un linguaggio non compilato, assicurarsi di includere un runtime compatibile nell'estensione.

Lambda supporta anche le estensioni interne. Un'estensione interna viene eseguita come thread separato nel processo di runtime. Il runtime avvia e arresta l'estensione interna. Un modo alternativo per integrarsi con l'ambiente Lambda consiste nell'utilizzare variabili d'ambiente e script wrapper specifici del linguaggio. Le estensioni interne consentono di configurare l'ambiente di runtime e modificare il comportamento di startup del processo di runtime.

È possibile aggiungere estensioni a una funzione evento in due modi. Per una funzione evento distribuita come archivio di file.zip, si distribuisce l'estensione come livello. Per una funzione evento definita come immagine contenitore, aggiungete le estensioni all'immagine del contenitore.

Ciclo di vita dell'ambiente di esecuzione Lambda

Il ciclo di vita dell'ambiente di esecuzione prevede le seguenti fasi:

Ogni fase inizia con un evento da Lambda al runtime e a tutte le estensioni registrate. Il runtime e ogni estensione segnalano il completamento inviando una richiesta API Next. Lambda congela l'ambiente di esecuzione quando ogni processo è stato completato e non ci sono eventi in sospeso.

Fase di init

Durante la fase Extension init, per ricevere gli eventi ogni estensione deve registrarsi con Lambda. Lambda utilizza il nome file completo dell'estensione per confermare che l'estensione abbia completato la sequenza di bootstrap. Pertanto, ogni chiamata Register API deve includere l'intestazione Lambda-Extension-Name con il nome file completo dell'estensione.

È possibile registrare fino a 10 estensioni per una funzione evento. Questo limite viene applicato tramite la chiamata Register API.

Dopo la registrazione di ogni estensione, Lambda inizia la fase Runtime init. Il processo di runtime chiama functionInit per avviare la fase Function init.

La fase Init viene completata dopo il runtime e ogni estensione registrata indica il completamento inviando una richiesta Next API.

Invoca fase

Quando una funzione evento Lambda viene richiamata in risposta a una richiesta Next API, Lambda invia un Invoke evento al runtime e a ogni estensione registrata per l'evento. Invoke

Durante l'invocazione, le estensioni esterne vengono eseguite in parallelo con la Event Function. Inoltre, continuano a funzionare dopo il completamento della Event Function. Puoi utilizzarlo per acquisire informazioni diagnostiche o per inviare registri, metriche e tracce a una posizione di tua scelta.

Dopo aver ricevuto la risposta Event Function dal runtime, Lambda restituisce la risposta al client, anche se le estensioni sono ancora in esecuzione.

La fase Invoke termina dopo il runtime e tutte le estensioni segnalano che vengono eseguite inviando una richiesta Next API.

Payload dell'evento: l'evento inviato al runtime (e alla funzione Lambda Event) contiene l'intera richiesta, le intestazioni (ad esempio) e RequestId il payload. L'evento inviato a ciascuna estensione contiene metadati che descrivono il contenuto dell'evento. Questo evento del ciclo di vita include il tipo di evento, l'ora di timeout della Event Function (deadlineMs)requestId, l'Amazon Resource Name (ARN) della Event Function richiamata e le intestazioni di tracciamento.

Le estensioni che desiderano accedere al corpo dell'evento Event Function possono utilizzare un SDK in runtime che comunica con l'estensione. Gli sviluppatori di Event Function utilizzano l'SDK in runtime per inviare il payload all'estensione quando viene richiamata la Event Function.

Ecco un esempio di payload:

{
    "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 di durata: l'impostazione del timeout della Event Function limita la durata dell'intera fase. Invoke Ad esempio, se impostate il timeout della funzione evento su 360 secondi, la funzione evento e tutte le estensioni devono essere completate entro 360 secondi. Si noti che non esiste una fase post-richiamo indipendente. La durata è il tempo totale impiegato per il completamento del runtime e delle chiamate di tutte le estensioni e non viene calcolata fino al termine dell'esecuzione della Event Function e di tutte le estensioni.

Impatto sulle prestazioni e sovraccarico di estensione: le estensioni possono influire sulle prestazioni della Event Function. In qualità di autore dell'estensione, hai il controllo sull'impatto sulle prestazioni della tua estensione. Ad esempio, se l'estensione esegue operazioni ad alta intensità di calcolo, la durata della funzione di evento aumenta perché l'estensione e il codice della funzione di evento condividono le stesse risorse della CPU. Inoltre, se l'estensione esegue operazioni estese dopo il completamento dell'invocazione della funzione di evento, la durata della funzione di evento aumenta perché la Invoke fase continua fino a quando tutte le estensioni segnalano che sono state completate.

Per aiutare a identificare l'impatto sulle prestazioni introdotto dalle estensioni sulla fase Invoke, Lambda esegue l'output del parametro PostRuntimeExtensionsDuration. Questa metrica misura il tempo cumulativo trascorso tra la richiesta Next API runtime e l'ultima richiesta Next API di estensione. Per misurare l'aumento della memoria utilizzata, utilizzare la metrica MaxMemoryUsed. Per ulteriori informazioni sulle metriche di Event Function, consulta. Utilizzo delle CloudWatch metriche con Lambda

Gli sviluppatori di Event Function possono eseguire diverse versioni delle loro Event Functions fianco a fianco per comprendere l'impatto di un'estensione specifica. Consigliamo agli autori delle estensioni di pubblicare il consumo previsto di risorse per consentire agli sviluppatori di Event Function di scegliere più facilmente l'estensione adatta.

Fase di arresto

Quando Lambda sta per chiudere il runtime, invia uno Shutdown a ciascuna estensione esterna registrata. Le estensioni possono utilizzare questo tempo per le attività di pulizia finali. L'evento Shutdown viene inviato in risposta a una richiesta Next API.

Limite di durata: la durata massima della fase Shutdown dipende dalla configurazione delle estensioni registrate:

Se il runtime o un'estensione non risponde all'evento Shutdown entro il limite, Lambda termina il processo utilizzando un segnale SIGKILL.

Payload evento: l'evento Shutdown contiene il motivo dell'arresto e il tempo rimanente in millisecondi.

shutdownReason include quanto segue:

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

Autorizzazioni e configurazione

Le estensioni vengono eseguite nello stesso ambiente di esecuzione della Lambda Event Function. Le estensioni condividono anche risorse con la funzione Event, come CPU, memoria e archiviazione /tmp su disco. Inoltre, le estensioni utilizzano lo stesso ruolo AWS Identity and Access Management (IAM) e lo stesso contesto di sicurezza della Event Function.

Autorizzazioni di accesso al file system e alla rete: le estensioni vengono eseguite nello stesso spazio dei nomi del file system e dei nomi di rete del runtime Event Function. Ciò significa che le estensioni devono essere compatibili con il sistema operativo associato. Se un'estensione richiede regole aggiuntive sul traffico di rete in uscita, è necessario applicare tali regole alla configurazione Event Function.

Variabili di ambiente: le estensioni possono accedere alle variabili di ambiente della funzione evento, ad eccezione delle seguenti variabili specifiche del processo di runtime:

Gestione dei guasti

Errori di inizializzazione: se un'estensione genera un errore, Lambda riavvia l'ambiente di esecuzione per imporre un comportamento coerente e per incoraggiare la risposta immediata agli errori per le estensioni. Inoltre, per alcuni clienti, le estensioni devono soddisfare esigenze mission-critical quali registrazione, sicurezza, governance e raccolta di dati di telemetria.

Errori di richiamo (ad esempio esaurimento della memoria, timeout della funzione Event): poiché le estensioni condividono risorse con il runtime, l'esaurimento della memoria influisce su di esse. Quando il runtime fallisce, tutte le estensioni e il runtime stesso partecipano alla fase Shutdown. Inoltre, il runtime viene riavviato, automaticamente come parte della chiamata corrente o tramite un meccanismo di reinizializzazione differita.

Se si verifica un errore (ad esempio un timeout della funzione evento o un errore di runtime) duranteInvoke, il servizio Lambda esegue un ripristino. Il reset si comporta come un evento Shutdown. Innanzitutto Lambda chiude il runtime, poi invia un evento Shutdown a ogni estensione esterna registrata. L'evento include il motivo dell'arresto. Se questo ambiente viene utilizzato per una nuova chiamata, l'estensione e il runtime vengono reinizializzati come parte della chiamata successiva.

Per una spiegazione più approfondita del diagramma precedente, consulta Errori durante la fase di richiamo.

Registri delle estensioni: Lambda invia l'output di registro delle estensioni CloudWatch a Logs. Lambda genera anche un evento di log aggiuntivo per ogni estensione durante Init. L'evento di log registra il nome e la preferenza di registrazione (evento, configurazione) in caso di successo o il motivo dell'errore in caso di errore.

Risoluzione dei problemi delle estensioni

Riferimento all'API delle estensioni

La specifica OpenAPI per le estensioni API versione 2020-01-01 è disponibile qui: extensions-api.zip

È possibile recuperare il valore dell'endpoint API dalla variabile di ambiente AWS_LAMBDA_RUNTIME_API. Per inviare una richiesta Register, utilizzare il prefisso 2020-01-01/ prima di ogni percorso API. Ad esempio:

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

Registrati

Durante Extension init, per ricevere gli eventi tutte le estensioni devono registrarsi con Lambda. Lambda utilizza il nome file completo dell'estensione per confermare che l'estensione abbia completato la sequenza di bootstrap. Pertanto, ogni chiamata Register API deve includere l'intestazione Lambda-Extension-Name con il nome file completo dell'estensione.

Le estensioni interne vengono avviate e arrestate dal processo di runtime, pertanto non sono autorizzate a registrarsi per l'evento Shutdown.

Percorso – /extension/register

Metodo – POST

Intestazioni della richiesta

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

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

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

Next

Le estensioni inviano una richiesta Next API per ricevere l'evento successivo, che può essere un evento Invoke o un evento Shutdown. Il corpo della risposta contiene il payload, che è un documento JSON che contiene i dati degli eventi.

L'estensione invia una richiesta Next API per segnalare che è pronta per ricevere nuovi eventi. Questa è una chiamata di blocco.

Non impostare un timeout sulla chiamata GET, poiché l'estensione può essere sospesa per un periodo di tempo fino a quando non c'è un evento da restituire.

Percorso – /extension/event/next

Metodo – GET

Errore di init

L'estensione utilizza questo metodo per segnalare un errore di inizializzazione a Lambda. Chiamalo quando l'estensione non riesce a inizializzare dopo che si è registrata. Dopo che Lambda riceve l'errore, le chiamate API successive hanno esito negativo. L'estensione dovrebbe terminare dopo aver ricevuto la risposta da Lambda.

Percorso – /extension/init/error

Metodo – POST

Questo campo è un oggetto JSON con la seguente struttura:

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

NB: Lambda accetta qualsiasi valore per errorType.

Nell'esempio seguente viene mostrato un messaggio di errore della funzione Lambda in cui la funzione non è stata in grado di analizzare i dati evento forniti nell'invocazione.

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

Errore di uscita

L'estensione utilizza questo metodo per segnalare un errore a Lambda prima di uscire. Chiamalo quando incontri un errore inaspettato. Dopo che Lambda riceve l'errore, le chiamate API successive hanno esito negativo. L'estensione dovrebbe terminare dopo aver ricevuto la risposta da Lambda.

Percorso – /extension/exit/error

Metodo – POST

Questo campo è un oggetto JSON con la seguente struttura:

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

NB: Lambda accetta qualsiasi valore per errorType.

Nell'esempio seguente viene mostrato un messaggio di errore della funzione Lambda in cui la funzione non è stata in grado di analizzare i dati evento forniti nell'invocazione.

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