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 vieMise en œuvre SnapStart de 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 la capture et après la 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éamorçage de générateurs de nombres aléatoires) à certains moments du cycle de vie de capture et de restauration. Si vous utilisez un environnement d'exécution géré qui SnapStart est pris en charge 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. Enregistrez vos hooks via l'API décrite dansImplémentation du code avant ou après les instantanés de fonctions Lambda.

Si vous utilisez vos propres images de conteneur de base, vos clients d'interface d'exécution (RIC) ou les images de base de Lambda pour provid.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 SnapStart d'utiliser votre fonction 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 pseudo-aléatoires sécurisés par chiffrement (CSPRNG) sont respectées.

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

  1. Option 1 : Si vous avez besoin de hooks avant et après la restauration pour exécuter une logique personnalisée lorsque la capture d'écran de votre fonction est reprise, suivez les instructions de la section. Mise en œuvre SnapStart de hooks de cycle

  2. Option 2 : Si vous n'avez pas besoin de ces crochets, activez-les SnapStart pour cette image 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 déjà le cycle de vie et fournissent les SnapStart 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.

Diagramme 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'invocation standard.

Mise en œuvre SnapStart de hooks de cycle

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

  1. Exécutez les hooks avant l'instantané et déclenchez le processus de capture instantanée : comme dernière étape du code d'initialisation de votre fonction, exécutez les crochets avant la capture instantanée si nécessaire et déclenchez le processus de capture instantanée. 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 à l'instantané génère ou renvoie une erreur, le moteur d'exécution publie l'erreur sur le point de terminaison. /runtime/init/error Consultez les exemples 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 Before Snapshot partagent un délai d'attente combiné de. max(function_timeout, 130 seconds) Si cette limite est dépassée, Lambda échoue à la PublishVersion demande. De plus/runtime/invocation/next, l'/runtime/restore/nextappel 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'invocation. Lorsque GET /runtime/restore/next renvoie 200, votre environnement d'exécution doit exécuter tous les hooks après restauration enregistrés avant de passer à la boucle d'invocation. Si un hook après restauration échoue, signalez l'erreur à/runtime/restore/error. Une fois les hooks post-restauration terminés, entrez dans la boucle d'invocation standard en appelant. GET /runtime/invocation/next À partir de ce moment, le comportement est identique à celui d'une fonction qui n'utilise pas SnapStart. Consultez les exemples 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

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 pour chaque phase :

Phase Erreur au point de terminaison de Que se passe-t-il en cas d'échec
Init/before-snapshot POST /runtime/init/error Lambda échoue à la PublishVersion demande. 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 avecerrorMessage,errorType, et un élément facultatifstackTrace.

Pour obtenir 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.