View a markdown version of this page

SnapStart Implémentation de crochets pour les images de conteneurs - AWS Lambda
Vue d’ensembleConditions préalablesAperçu du cycle de vieMettre en œuvre SnapStart des hooks de cycleGestion des erreurs

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

SnapStart Implémentation de crochets pour les images de conteneurs

Vue d’ensemble

Lors de l'utilisation SnapStart avec une fonction d'image de conteneur, le moteur d'exécution doit coordonner le cycle de vie de la fonction et invoquer les hooks avant capture et après restauration pendant les phases de cycle de vie appropriées. Ces hooks vous permettent d'exécuter une logique personnalisée (telle que l'actualisation des informations d'identification ou le réensemencement de générateurs de nombres aléatoires) à certains moments du cycle de vie des snapshots et des restaurations. Si vous utilisez un environnement d'exécution géré supporté ou les images de base correspondantes pour ces environnements d'exécution (Java version 11+, Python version 3.12+ et .NET version 8+), Lambda coordonne le cycle de vie pour vous. SnapStart Enregistrez vos hooks via l'API décrite dansImplémenter le code avant ou après les instantanés de la fonction d'événement Lambda.

Si vous utilisez vos propres images de conteneur de base, des clients d'interface d'exécution (RIC) ou les images de base de Lambda pour provided.al2023 ou Ruby Node.js, suivez les étapes de cette page pour les utiliser. SnapStart

Conditions préalables

Lorsque Lambda restaure une fonction à partir d'un instantané, tout état défini lors de l'initialisation, tel que les générateurs de nombres aléatoires, les identifiants uniques et les informations d'identification mises en cache, est partagé dans tous les environnements d'exécution restaurés à partir de cet instantané. Avant de l'utiliser SnapStart avec votre fonction d'événement Lambda basée sur une image de conteneur, vérifiez Gérer l'unicité avec Lambda SnapStart et assurez-vous que les exigences décrites dans Utiliser des générateurs de nombres pseudoaléatoires (CSPRNG) sécurisés par chiffrement sont respectées.

Après avoir vérifié que les exigences sont satisfaites, choisissez l'une des deux options suivantes :

  1. Option 1 : Si vous avez besoin de crochets avant et après restauration pour exécuter une logique personnalisée lorsque le snapshot de votre fonction est repris, suivez les instructions de la section. Mettre en œuvre SnapStart des hooks de cycle

  2. Option 2 : Si vous n'avez pas besoin de ces hooks, activez cette image SnapStart de conteneur en spécifiant l'étiquette suivante dans votre Dockerfile :

LABEL com.amazonaws.lambda.feature.snapstart="Allow"

Si votre image de conteneur n'implémente pas l'/restore/nextAPI et n'inclut pas l'étiquette, la publication de la version échouera.

Note

Ces prérequis ne sont pas obligatoires si vous utilisez des images de base gérées par Lambda pour Java (version 11+), Python (version 3.12+) et .NET (version 8+) car elles coordonnent SnapStart déjà le cycle de vie et répondent aux exigences d'unicité.

Aperçu du cycle de vie

Le schéma suivant montre l'ordre des appels d'API Runtime qu'un environnement d'exécution SnapStart personnalisé est censé effectuer. Tous les appels font partie du contrat d'API Runtime, tandis que les appels #3, #4, #5 et #6 sont spécifiques à SnapStart.

Schéma de séquence montrant l'ordre des appels d'API Runtime pour un environnement d'exécution SnapStart personnalisé : init, hooks before-snapshot, GET/runtime/restore/next, hooks after-restore et boucle d'appel standard.

Mettre en œuvre SnapStart des hooks de cycle

Pour utiliser SnapStart les fonctions d'image de votre conteneur, suivez les étapes ci-dessous :

  1. Exécutez les hooks avant l'instantané et déclenchez le processus de capture d'écran : comme dernière étape du code d'initialisation de votre fonction, exécutez les crochets avant l'instantané si nécessaire et déclenchez le processus de capture d'écran. Effectuez ces étapes uniquement si cette option SnapStart est activée, en vérifiant que la valeur de la variable d'AWS_LAMBDA_INITIALIZATION_TYPEenvironnement est définie sursnap-start. Exécutez vos hooks enregistrés avant la capture d'écran, puis appelez GET /runtime/restore/next pour déclencher le processus de capture instantanée. Si un hook antérieur à la capture d'écran génère ou renvoie une erreur, le moteur d'exécution publie l'erreur sur le point de terminaison. /runtime/init/error Consultez l'exemple de pseudo-code ci-dessous :

    # After all initialization code has finished:

    READ initialization_type FROM environment variable "AWS_LAMBDA_INITIALIZATION_TYPE"

    IF initialization_type IS "snap-start" THEN

        TRY
            EXECUTE registered before-snapshot hooks
        ON ERROR
            POST error to /runtime/init/error
                SET header  Lambda-Runtime-Function-Error-Type  TO  <Category.Reason>
                SET body    TO  { errorMessage, errorType, stackTrace }
            EXIT process with non-zero code

        # Signal readiness for snapshot
        SEND GET request to /runtime/restore/next
        # The request blocks until Lambda restores the execution environment from the snapshot, then returns HTTP 200.

    END IF
    Note

    La phase d'initialisation et les hooks précédant la capture d'écran partagent un délai d'expiration combiné de. max(function_timeout, 130 seconds) Si cette limite est dépassée, Lambda échoue à la PublishVersion demande. De plus/runtime/invocation/next, un /runtime/restore/next appel est un appel bloquant. Il bloque jusqu'à ce que Lambda restaure l'environnement d'exécution à partir du snapshot.

  2. Exécutez les hooks après la restauration, puis entrez dans la boucle d'appel. Lorsque GET /runtime/restore/next renvoie 200, votre environnement d'exécution doit exécuter tous les hooks enregistrés après restauration avant de passer à la boucle d'appel. Si un hook après restauration échoue, signalez l'erreur à/runtime/restore/error. Une fois les hooks après restauration terminés, entrez dans la boucle d'appel standard en appelantGET /runtime/invocation/next. À partir de ce moment, le comportement est identique à celui d'une fonction qui n'utilise pas SnapStart. Consultez l'exemple de pseudo-code ci-dessous :

    # After the snapshot has been restored
# (i.e., GET /runtime/restore/next has returned HTTP 200):

    TRY
        EXECUTE registered after-restore hooks
    ON ERROR
        POST error to /runtime/restore/error
            SET header  Lambda-Runtime-Function-Error-Type  TO  <Category.Reason>
            SET body    TO  { errorMessage, errorType, stackTrace }

# Proceed to the invoke loop
       GET /runtime/invocation/next

Gestion des erreurs

Si un hook échoue, le moteur d'exécution doit signaler l'erreur au point de terminaison d'API approprié et quitter le processus. Le tableau ci-dessous résume le comportement de chaque phase :

Phase Erreur : point de terminaison API Que se passe-t-il en cas d'échec
Initialiser/ avant-instantané POST /runtime/init/error Lambda échoue à la demande. PublishVersion Quittez le processus.
After-restore POST /runtime/restore/error Lambda échoue à l'invocation en vol et détruit l'environnement d'exécution. Quittez le processus.

Pour les deux points de terminaison de l'API, définissez l'Lambda-Runtime-Function-Error-Typeen-tête sur une valeur au format <Category.Reason> (par exemple, Runtime.BeforeSnapshotError ouRuntime.AfterRestoreError). Incluez un corps d'erreur avec errorMessageerrorType, et un élément facultatifstackTrace.

Pour la spécification complète des points de terminaison de l'API et les codes de réponse, consultez Erreur d’initialisation et Erreur de restauration (applicable uniquement pour SnapStart) dans la référence de l'API Runtime.