aws lambda web adapter
v0.8.4
Uma ferramenta para executar aplicações web no AWS Lambda
AWS Lambda Web Adaptor permite que os desenvolvedores criem aplicativos web (http api) com estruturas familiares (por exemplo, Express.js, Next.js, Flask, SpringBoot, ASP.NET e Laravel, qualquer coisa fala HTTP 1.1/1.0) e execute-os no AWS Lambda . A mesma imagem do Docker pode ser executada no AWS Lambda, Amazon EC2, AWS Fargate e computadores locais.
O AWS Lambda Web Adaptor funciona com funções Lambda empacotadas como imagens docker e pacotes Zip.
Para usar o Lambda Web Adaptor com imagens docker, empacote seu aplicativo web (http api) em um Dockerfile e adicione uma linha para copiar o binário do Lambda Web Adaptor para /opt/extensions dentro do seu contêiner:
COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.8.4 /lambda-adapter /opt/extensions/lambda-adapterImagens base não AWS podem ser usadas, já que o Runtime Interface Client é fornecido com o Lambda Web Adaptor.
Por padrão, o Lambda Web Adaptor assume que o aplicativo web está escutando na porta 8080. Caso contrário, você pode especificar a porta por meio da configuração.
Os binários pré-compilados do Lambda Web Adaptor são fornecidos no repositório público do ECR: public.ecr.aws/awsguru/aws-lambda-adapter. Imagens multi-arch também são fornecidas neste repositório. Funciona na arquitetura de CPU x86_64 e arm64.
Abaixo está um Dockerfile para um exemplo de aplicativo nodejs.
FROM public.ecr.aws/docker/library/node:20-slim
COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.8.4 /lambda-adapter /opt/extensions/lambda-adapter
ENV PORT=7000
WORKDIR "/var/task"
ADD src/package.json /var/task/package.json
ADD src/package-lock.json /var/task/package-lock.json
RUN npm install --omit=dev
ADD src/ /var/task
CMD [ "node" , "index.js" ]Isso funciona com qualquer imagem base, exceto imagens base gerenciadas pela AWS. Para usar imagens base gerenciadas pela AWS, você precisa substituir o ENTRYPOINT para iniciar seu aplicativo web.
O AWS Lambda Web Adaptor também funciona com tempos de execução do Lambda gerenciados pela AWS. Você precisa fazer três coisas:
anexe a camada do Lambda Web Adaptor à sua função.
arn:aws:lambda:${AWS::Region}:753240598075:layer:LambdaAdapterLayerX86:23arn:aws:lambda:${AWS::Region}:753240598075:layer:LambdaAdapterLayerArm64:23 arn:aws-cn:lambda:cn-north-1:041581134020:layer:LambdaAdapterLayerX86:23arn:aws-cn:lambda:cn-northwest-1:069767869989:layer:LambdaAdapterLayerX86:23 configure a variável de ambiente Lambda AWS_LAMBDA_EXEC_WRAPPER para /opt/bootstrap .
defina o manipulador de função para o script de inicialização do seu aplicativo da web. por exemplo, run.sh .
Para obter detalhes, verifique o exemplo do aplicativo Node.js.
Quando um novo Lambda Execution Environment é inicializado, o Lambda Web Adaptor será inicializado como uma extensão Lambda, seguido pelo aplicativo web.
Por padrão, o Lambda Web Adaptor enviará solicitações HTTP GET para o aplicativo da web em http://127.0.0.1:8080/ . A porta e o caminho podem ser personalizados com duas variáveis de ambiente: AWS_LWA_READINESS_CHECK_PORT e AWS_LWA_READINESS_CHECK_PATH .
O Lambda Web Adaptor tentará novamente essa solicitação a cada 10 milissegundos até que o aplicativo da web retorne uma resposta HTTP ( código de status >= 100 e < 500 ) ou a função expire.
Além disso, você pode configurar o adaptador para realizar a verificação de prontidão com conexão TCP, definindo AWS_LWA_READINESS_CHECK_PROTOCOL como tcp .
Depois de passar na verificação de prontidão, o Lambda Web Adaptor iniciará o Lambda Runtime e encaminhará as invocações para a aplicação web.
A porta/caminho de verificação de prontidão e a porta de tráfego podem ser configuradas usando variáveis de ambiente. Essas variáveis de ambiente podem ser definidas no arquivo docker ou como configuração da função Lambda.
| Variável de ambiente | Descrição | Padrão |
|---|---|---|
| AWS_LWA_PORT/PORTA* | porto de tráfego | "8080" |
| AWS_LWA_READINESS_CHECK_PORT/READINESS_CHECK_PORT* | porta de verificação de prontidão, padrão para a porta de tráfego | PORTA |
| AWS_LWA_READINESS_CHECK_PATH/READINESS_CHECK_PATH* | caminho de verificação de prontidão | "/" |
| AWS_LWA_READINESS_CHECK_PROTOCOL/READINESS_CHECK_PROTOCOL* | protocolo de verificação de prontidão: "http" ou "tcp", o padrão é "http" | "http" |
| AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS | O código de status HTTP mínimo considerado não íntegro | "500" |
| AWS_LWA_ASYNC_INIT/ASYNC_INIT* | habilitar inicialização assíncrona para funções de inicialização longas | "falso" |
| AWS_LWA_REMOVE_BASE_PATH/REMOVE_BASE_PATH* | o caminho base a ser removido do caminho da solicitação | Nenhum |
| AWS_LWA_ENABLE_COMPRESSION | ativar a compactação gzip para o corpo da resposta | "falso" |
| AWS_LWA_INVOKE_MODE | Modo de invocação da função Lambda: "buffered" ou "response_stream", o padrão é "buffered" | "tamponado" |
| AWS_LWA_PASS_THROUGH_PATH | o caminho para receber cargas de eventos que são transmitidas de gatilhos não HTTP | "/eventos" |
| AWS_LWA_AUTHORIZATION_SOURCE | um nome de cabeçalho a ser substituído por Authorization | Nenhum |
Observação: usamos o prefixo "AWS_LWA_" para definir o namespace de todas as variáveis de ambiente usadas pelo Lambda Web Adaptor. Os originais serão suportados até chegarmos à versão 1.0.
AWS_LWA_PORT / PORT - O Lambda Web Adaptor enviará tráfego para esta porta. Esta é a porta em que seu aplicativo da web está escutando. Dentro do ambiente de execução do Lambda, o aplicativo da web é executado como um usuário não root e não tem permissão para escutar em portas inferiores a 1024. Evite também as portas 9001 e 3000. A API Lambda Runtime está na porta 9001. A extensão CloudWatch Lambda Insight usa a porta 3000 .
AWS_LWA_ASYNC_INIT/ASYNC_INIT – Os tempos de execução gerenciados pelo Lambda oferecem até 10 segundos para inicialização da função. Durante esse período, as funções Lambda têm pico de CPU para acelerar a inicialização e são gratuitas. Se uma função lambda não puder concluir a inicialização em 10 segundos, o Lambda reiniciará a função e cobrará pela inicialização. Para ajudar as funções a usar esse tempo de inicialização livre de 10 segundos e evitar a reinicialização, o Lambda Web Adaptor oferece suporte à inicialização assíncrona. Quando esse recurso está habilitado, o Lambda Web Adaptor executa a verificação de prontidão em até 9,8 segundos. Se o aplicativo web não estiver pronto até então, o Lambda Web Adapter sinaliza ao serviço Lambda que o init foi concluído e continua a verificação de prontidão no manipulador. Este recurso está desabilitado por padrão. Habilite-o definindo a variável de ambiente AWS_LWA_ASYNC_INIT como true .
AWS_LWA_REMOVE_BASE_PATH / REMOVE_BASE_PATH – O valor desta variável de ambiente informa ao adaptador se o aplicativo está sendo executado em um caminho base. Por exemplo, você poderia ter configurado seu API Gateway para ter um recurso /orders/{proxy+} e um recurso /catalog/{proxy+}. Cada recurso é tratado por funções Lambda separadas. Por esse motivo, o aplicativo dentro do Lambda pode não estar ciente da existência do caminho /orders. Use REMOVE_BASE_PATH para remover o prefixo /orders ao rotear solicitações para o aplicativo. O padrão é uma string vazia. Confira o exemplo do SpringBoot.
AWS_LWA_ENABLE_COMPRESSION - O Lambda Web Adaptor oferece suporte à compactação gzip para o corpo da resposta. Este recurso está desabilitado por padrão. Habilite-o definindo a variável de ambiente AWS_LWA_ENABLE_COMPRESSION como true . Quando ativado, isso compactará as respostas, a menos que seja uma imagem determinada pelo tipo de conteúdo começando com image ou a resposta tenha menos de 32 bytes. Isso também compactará a resposta de streaming em partes HTTP/1.1.
AWS_LWA_INVOKE_MODE - modo de invocação de função Lambda, deve corresponder ao modo de invocação de URL de função. O padrão é "bufferizado". Quando configurado como "response_stream", o Lambda Web Adaptor transmitirá a resposta para o blog do serviço Lambda. Confira o exemplo FastAPI com Response Streaming.
AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS - permite personalizar quais códigos de status HTTP são considerados íntegros e quais não são
AWS_LWA_PASS_THROUGH_PATH – Caminho para receber cargas úteis de eventos transmitidas por gatilhos de eventos não HTTP. O padrão é "/eventos".
AWS_LWA_AUTHORIZATION_SOURCE – Quando definido, o Lambda Web Adaptor substitui o nome do cabeçalho especificado por Authorization antes de fazer proxy de uma solicitação. Isso é útil quando você usa o URL da função Lambda com o tipo de autenticação IAM, que reserva o cabeçalho de autorização para autenticação do IAM, mas você ainda deseja usar o cabeçalho de autorização para seus aplicativos de back-end. Este recurso está desabilitado por padrão.
Contexto de solicitação são metadados que o API Gateway envia ao Lambda para uma solicitação. Geralmente contém requestId, requestTime, apiId, identidade e autorizador. A identidade e o autorizador são úteis para obter a identidade do cliente para autorização. O Guia do desenvolvedor do API Gateway contém mais detalhes aqui.
O Lambda Web Adapter encaminha essas informações para a aplicação web em um cabeçalho Http denominado "x-amzn-request-context". No aplicativo Web, você pode recuperar o valor desse cabeçalho http e desserializá-lo em um objeto JSON. Confira Express.js em Zip para saber como usá-lo.
Contexto Lambda é um objeto que o Lambda passa para o manipulador de função. Este objeto fornece informações sobre a invocação, função e ambiente de execução. Você pode encontrar uma lista completa de propriedades acessíveis através do Contexto Lambda aqui
O Lambda Web Adapter encaminha essas informações para o aplicativo da web em um cabeçalho Http denominado "x-amzn-lambda-context". No aplicativo Web, você pode recuperar o valor desse cabeçalho http e desserializá-lo em um objeto JSON. Confira Express.js em Zip para saber como usá-lo.
Para uma função com extensões Lambda registradas, o Lambda habilita a fase de encerramento para a função. Quando o serviço Lambda está prestes a encerrar um ambiente de execução Lambda, ele envia um sinal SIGTERM para o tempo de execução e, em seguida, um evento SHUTDOWN para cada extensão externa registrada. Os desenvolvedores podem capturar o sinal SIGTERM nas funções lambda e executar tarefas de desligamento elegantes. O Express.js dá um exemplo simples. Mais detalhes neste repositório.
O Lambda Web Adaptor permite que os desenvolvedores desenvolvam aplicações web localmente com ferramentas e depuradores familiares: basta executar a aplicação web localmente e testá-la. Se quiser simular o ambiente Lambda Runtime localmente, você pode usar o AWS SAM CLI. O comando a seguir inicia um endpoint de gateway de API local e simula o ambiente de execução do tempo de execução do Lambda.
sam local start-api Observe que sam local inicia um emulador de interface Lambda Runtime na porta 8080. Portanto, seu aplicativo da web deve evitar a porta 8080 se você planeja usar sam local .
O Lambda Web Adaptor também oferece suporte a todos os gatilhos de eventos não HTTP, como SQS, SNS, S3, DynamoDB, Kinesis, Kafka, EventBridge e Bedrock Agents. O adaptador encaminha a carga útil do evento para o aplicativo da web por meio de postagem http para um caminho definido pela variável de ambiente AWS_LWA_PASS_THROUGH_PATH . Por padrão, esse caminho é definido como /events . Ao receber o payload do evento do corpo da solicitação, o aplicativo web deve processá-lo e retornar os resultados como uma resposta JSON. Verifique SQS Express.js e Bedrock Agent FastAPI em exemplos Zip.
Este projeto foi inspirado em vários projetos comunitários.
Vários projetos também fornecem recursos semelhantes aos pacotes/estruturas específicas de linguagem.
Consulte CONTRIBUINDO para obter mais informações.
Este projeto está licenciado sob a licença Apache-2.0.
