View a markdown version of this page

Implementando hooks SnapStart para imagens de contêineres - AWS Lambda
Visão geralPré-requisitosVisão geral do ciclo de vidaImplementação dos ganchos do ciclo de vida do SnapStartTratamento de erros

Implementando hooks SnapStart para imagens de contêineres

Visão geral

Ao usar o SnapStart com uma função de imagem de contêiner, o runtime precisa coordenar o ciclo de vida da função e invocar os hooks antes do snapshot e após a restauração durante as fases apropriadas do ciclo de vida. Esses hooks permitem que você execute uma lógica personalizada (como atualizar credenciais ou reinicializar geradores de números aleatórios) em pontos do ciclo de vida de snapshot e restauração. Se você usar um runtime gerenciado em que o SnapStart seja compatível ou usar as imagens base correspondentes a esses runtimes (Java versão 11+, Python versão 3.12+ e .NET versão 8+), o Lambda coordenará o ciclo de vida para você. Registre seus hooks por meio da API descrita em Implementar código antes ou depois dos snapshots da função do Lambda.

Se você usa suas próprias imagens base de contêiner, Runtime Interface Clients (RICs) ou imagens base do Lambda para provided.al2023, Node.js ou Ruby, siga as etapas nesta página para usar o SnapStart.

Pré-requisitos

Quando o Lambda restaura uma função a partir de um snapshot, qualquer estado definido durante a inicialização, como geradores de números aleatórios, IDs exclusivos e credenciais em cache, é compartilhado em todos os ambientes de execução restaurados a partir desse snapshot. Antes de usar o SnapStart com sua função do Lambda baseada em imagem de contêiner, analise Tratamento da exclusividade com o Lambda SnapStart e garanta que os requisitos descritos em Use geradores de números pseudoaleatórios criptograficamente seguros (CSPRNGs) sejam cumpridos.

Depois de validar se os requisitos foram cumpridos, escolha uma das duas opções a seguir:

  1. Opção 1: se você precisar de hooks antes do snapshot e após a restauração para executar a lógica personalizada quando o snapshot da função for retomado, siga as instruções na seção Implementação dos ganchos do ciclo de vida do SnapStart.

  2. Opção 2: se você não precisar desses hooks, habilite o SnapStart para a imagem de contêiner especificando o seguinte rótulo em seu Dockerfile:

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

Se sua imagem de contêiner não implementar a API /restore/next nem incluir o rótulo, a publicação da versão falhará.

nota

Esses pré-requisitos não são necessários se você usar imagens base gerenciadas pelo Lambda para Java (versão 11+), Python (versão 3.12+) e .NET (versão 8+), pois elas já coordenam o ciclo de vida do SnapStart e fornecem os requisitos de exclusividade.

Visão geral do ciclo de vida

O diagrama a seguir mostra a ordem das chamadas de API do Runtime realizadas por um runtime personalizado do SnapStart. Todas as chamadas fazem parte do contrato da API do Runtime, enquanto as chamadas #3, #4, #5 e #6 são específicas do SnapStart.

Diagrama em sequência que mostra a ordem das chamadas de API do Runtime relacionadas a um runtime personalizado do SnapStart: init, hooks antes do snapshot, GET /runtime/restore/next, hooks após a restauração e o loop de invocação padrão.

Implementação dos ganchos do ciclo de vida do SnapStart

Para usar o SnapStart com as funções de imagem de contêiner, siga as etapas abaixo:

  1. Execute os hooks antes do snapshot e acione o processo de snapshots: como última etapa do código de inicialização da função, execute os hooks antes do snapshot, se necessário, e acione o processo de snapshots. Execute essas etapas somente se o SnapStart estiver habilitado, verificando se o valor da variável do ambiente AWS_LAMBDA_INITIALIZATION_TYPE está definido como snap-start. Execute seus hooks antes do snapshot registrados e, em seguida, chame GET /runtime/restore/next para acionar o processo de snapshots. Se um hook antes do snapshot gerar ou retornar um erro, o runtime publicará o erro no endpoint /runtime/init/error. Veja os exemplos de pseudocódigo abaixo:

    # 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
    nota

    A fase de inicialização e os hooks antes do snapshot compartilham um tempo limite combinado de max(function_timeout, 130 seconds). Se esse limite for excedido, o Lambda falhará na solicitação PublishVersion. Além disso, assim como /runtime/invocation/next, a chamada /runtime/restore/next é uma chamada de bloqueio. Ela faz o bloqueio até que o Lambda restaure o ambiente de execução a partir do snapshot.

  2. Execute os hooks após a restauração e, em seguida, entre no loop de invocação. Quando GET /runtime/restore/next retorna 200, seu runtime precisa executar todos os hooks registrados após a restauração antes de prosseguir para o loop de invocação. Se um hook após a restauração falhar, comunique o erro para /runtime/restore/error. Depois que os hooks após a restauração forem concluídos, entre no loop de invocação padrão chamando GET /runtime/invocation/next. A partir desse momento, o comportamento é idêntico ao de uma função que não usa o SnapStart. Veja os exemplos de pseudocódigo abaixo:

    # 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

Tratamento de erros

Se um hook falhar, o runtime precisará reportar o erro ao endpoint apropriado da API e sair do processo. A tabela abaixo resume o comportamento de cada fase:

Fase Endpoint da API de erro O que acontece em caso de falha
Inicializar/antes do snapshot POST /runtime/init/error O Lambda falha na solicitação PublishVersion. Saia do processo.
Após a restauração POST /runtime/restore/error O Lambda falha na invocação em andamento e destrói o ambiente de execução. Saia do processo.

Para os dois endpoints da API, defina o cabeçalho Lambda-Runtime-Function-Error-Type com um valor no formato <Category.Reason> (por exemplo, Runtime.BeforeSnapshotError ou Runtime.AfterRestoreError). Inclua um corpo de erro com errorMessage, errorType e um stackTrace opcional.

Para obter a especificação completa do endpoint da API e os códigos de resposta, consulte Erro de inicialização e Erro de restauração (aplicável somente ao SnapStart) na referência da API do Runtime.