Utilizzo delle estensioni Lambda API per creare estensioni

Gli autori di funzioni Lambda utilizzano le estensioni per integrare Lambda con gli strumenti preferiti per il monitoraggio, l'osservabilità, la sicurezza e la governance. Gli autori delle funzioni 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. Questa sezione descrive come utilizzare le estensioni LambdaAPI, il ciclo di vita dell'ambiente di esecuzione Lambda e il riferimento alle estensioni Lambda. API

In qualità di autore di estensioni, puoi utilizzare le estensioni Lambda API per integrarle a fondo nell'ambiente di esecuzione Lambda. L'estensione può registrarsi per funzioni ed eventi del ciclo di vita dell'ambiente di esecuzione. 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, puoi utilizzare i Runtime Logs API per ricevere un flusso di log.

Un'estensione esterna viene eseguita come processo indipendente nell'ambiente di esecuzione e continua a funzionare anche dopo che la chiamata della funzione è stata completamente elaborata. Poiché le estensioni esterne vengono eseguite come processi, è possibile scriverle in un linguaggio diverso da quella della funzione. 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 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 in due modi. Per una funzione distribuita come archivio di file con estensione zip, è possibile distribuire l'estensione come livello. Per una funzione definita come immagine di container, le estensioni vengono aggiunte all'immagine del container.

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. Next API 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 Register API chiamata deve includere l'Lambda-Extension-Nameintestazione con il nome file completo dell'estensione.

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

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 Init fase viene completata dopo l'esecuzione e ogni estensione registrata indica il completamento inviando una Next API richiesta.

Invoca fase

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

Durante la chiamata, le estensioni esterne vengono eseguite in parallelo con la funzione. Continuano anche a funzionare dopo che la funzione è stata completata. In questo modo è possibile acquisire informazioni diagnostiche o inviare log, parametri e tracce in una posizione di propria scelta.

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

La Invoke fase termina dopo il runtime e tutte le estensioni segnalano che è stata completata inviando una richiesta. Next API

Payload evento: l'evento inviato al runtime (e alla funzione Lambda) contiene l'intera richiesta, le intestazioni (ad esempio RequestId) e 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 in cui la funzione scade (deadlineMs)requestId, l'Amazon Resource Name (ARN) della funzione richiamata e le intestazioni di tracciamento.

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

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

Duration limit (Limite di durata): l'impostazione di timeout della funzione limita la durata dell'intera fase Invoke. Ad esempio, se si imposta il timeout della funzione come 360 secondi, la funzione 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 funzione e di tutte le estensioni.

Impatto sulle prestazioni e sovraccarico di estensione: le estensioni possono influire sulle prestazioni delle funzioni In qualità di autore dell'estensione, hai il controllo sull'impatto sulle prestazioni della tua estensione. Ad esempio, se l'estensione esegue operazioni a elaborazione intensiva, la durata della funzione aumenta perché l'estensione e il codice della funzione condividono le stesse risorse. CPU Inoltre, se l'estensione esegue operazioni estese al termine dell'invocazione della funzione, la durata della funzione aumenta perché la fase Invoke continua fino a quando tutte le estensioni non 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 di runtime e l'ultima Next API richiesta di estensione. Next API Per misurare l'aumento della memoria utilizzata, utilizzare la metrica MaxMemoryUsed. Per ulteriori informazioni sugli stati delle funzioni, consultare Visualizza le metriche per le funzioni Lambda.

Gli sviluppatori di funzioni possono eseguire diverse versioni delle loro funzioni fianco a fianco per comprendere l'impatto di un'estensione specifica. Si consiglia agli autori di estensioni di pubblicare il consumo previsto di risorse per semplificare la scelta di un'estensione adatta per gli sviluppatori di funzioni.

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'Shutdownevento viene inviato in risposta a una richiesta. Next API

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

Per una funzione con estensioni esterne, Lambda riserva fino a 300 ms (500 ms per un runtime con un'estensione interna) per consentire al processo di runtime di eseguire un arresto regolare. Lambda assegna la parte rimanente del limite di 2.000 ms per l'arresto delle estensioni esterne.

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 funzione Lambda. Le estensioni condividono anche risorse con la funzioneCPU, ad esempio 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 funzione.

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

Variabili di ambiente: le estensioni possono accedere alle variabili di ambiente, della funzione, 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.

Invocare errori (come memoria esaurita, timeout funzione): poiché le estensioni condividono le risorse con il runtime, sono influenzata dall'esaurimento della memoria. Quando il runtime fallisce, tutte le estensioni e il runtime stesso partecipano alla fase Shutdown. Inoltre, il runtime viene riavviato automaticamente come parte dell'invocazione corrente o tramite un meccanismo di reinizializzazione differita.

Se si verifica un errore (ad esempio un timeout della funzione o un errore di runtime) durante Invoke, il servizio Lambda esegue un reset. 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 alle estensioni API

La API specifica Open per la API versione 2020-01-01 delle estensioni è disponibile qui: extensions-api.zip

È possibile recuperare il valore dell'endpoint dalla variabile di ambiente. API AWS_LAMBDA_RUNTIME_API Per inviare una Register richiesta, utilizzate il prefisso 2020-01-01/ prima di ogni percorso. API Per 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 Register API chiamata deve includere l'Lambda-Extension-Nameintestazione con il nome completo del file 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 Next API richiesta per ricevere l'evento successivo, che può essere un Invoke evento o un Shutdown evento. Il corpo della risposta contiene il payload, che è un JSON documento che contiene i dati dell'evento.

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

Non impostate un timeout per la GET chiamata, poiché l'estensione può essere sospesa per un periodo di tempo fino al ritorno di un evento.

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, nessun'altra API chiamata ha esito positivo. L'estensione dovrebbe terminare dopo aver ricevuto la risposta da Lambda.

Percorso – /extension/init/error

Metodo — POST

Questo campo è un JSON oggetto 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, nessun'altra API chiamata ha esito positivo. L'estensione dovrebbe terminare dopo aver ricevuto la risposta da Lambda.

Percorso – /extension/exit/error

Metodo — POST

Questo campo è un JSON oggetto 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": [ ]
}