aws lambda web adapter
v0.8.4
AWS Lambda에서 웹 애플리케이션을 실행하는 도구
AWS Lambda Web Adapter를 사용하면 개발자는 익숙한 프레임워크(예: Express.js, Next.js, Flask, SpringBoot, ASP.NET 및 Laravel, HTTP 1.1/1.0을 지원하는 모든 항목)를 사용하여 웹 앱(http api)을 구축하고 AWS Lambda에서 실행할 수 있습니다. . 동일한 도커 이미지는 AWS Lambda, Amazon EC2, AWS Fargate 및 로컬 컴퓨터에서 실행될 수 있습니다.
AWS Lambda Web Adapter는 Docker 이미지와 Zip 패키지로 패키지된 Lambda 함수와 함께 작동합니다.
Docker 이미지와 함께 Lambda 웹 어댑터를 사용하려면 Dockerfile에 웹 앱(http api)을 패키징하고 한 줄을 추가하여 Lambda 웹 어댑터 바이너리를 컨테이너 내부의 /opt/extensions에 복사합니다.
COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.8.4 /lambda-adapter /opt/extensions/lambda-adapter런타임 인터페이스 클라이언트는 Lambda 웹 어댑터와 함께 제공되므로 AWS가 아닌 기본 이미지를 사용할 수 있습니다.
기본적으로 Lambda 웹 어댑터는 웹 앱이 포트 8080에서 수신 대기 중이라고 가정합니다. 그렇지 않은 경우 구성을 통해 포트를 지정할 수 있습니다.
사전 컴파일된 Lambda 웹 어댑터 바이너리는 ECR 공개 저장소(public.ecr.aws/awsguru/aws-lambda-adapter)에 제공됩니다. 이 저장소에는 다중 아키텍처 이미지도 제공됩니다. x86_64 및 arm64 CPU 아키텍처 모두에서 작동합니다.
다음은 nodejs 애플리케이션 예시에 대한 Dockerfile입니다.
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" ]이는 AWS 관리형 기본 이미지를 제외한 모든 기본 이미지에서 작동합니다. AWS 관리형 기본 이미지를 사용하려면 ENTRYPOINT를 재정의하여 웹 앱을 시작해야 합니다.
AWS Lambda Web Adapter는 AWS 관리형 Lambda 런타임에서도 작동합니다. 세 가지 작업을 수행해야 합니다.
Lambda 웹 어댑터 계층을 함수에 연결합니다.
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 Lambda 환경 변수 AWS_LAMBDA_EXEC_WRAPPER /opt/bootstrap 으로 구성합니다.
웹 애플리케이션 시작 스크립트에 함수 핸들러를 설정합니다. 예를 들어 run.sh .
자세한 내용은 Node.js 애플리케이션 예시를 확인하세요.
새로운 Lambda 실행 환경이 시작되면 Lambda 웹 어댑터가 Lambda 확장으로 부팅되고 이어서 웹 애플리케이션이 부팅됩니다.
기본적으로 Lambda 웹 어댑터는 http://127.0.0.1:8080/ 의 웹 애플리케이션에 HTTP GET 요청을 보냅니다. 포트와 경로는 AWS_LWA_READINESS_CHECK_PORT 및 AWS_LWA_READINESS_CHECK_PATH 두 가지 환경 변수를 사용하여 사용자 지정할 수 있습니다.
Lambda 웹 어댑터는 웹 애플리케이션이 HTTP 응답( 상태 코드 >= 100 및 < 500 )을 반환하거나 함수가 시간 초과될 때까지 10밀리초마다 이 요청을 다시 시도합니다.
또한 AWS_LWA_READINESS_CHECK_PROTOCOL tcp 로 설정하여 TCP 연결을 통해 준비 상태 확인을 수행하도록 어댑터를 구성할 수 있습니다.
준비 확인을 통과한 후 Lambda 웹 어댑터는 Lambda 런타임을 시작하고 호출을 웹 애플리케이션에 전달합니다.
준비 상태 확인 포트/경로 및 트래픽 포트는 환경 변수를 사용하여 구성할 수 있습니다. 이러한 환경 변수는 docker 파일 내에서 또는 Lambda 함수 구성으로 정의할 수 있습니다.
| 환경변수 | 설명 | 기본 |
|---|---|---|
| AWS_LWA_PORT / 포트* | 교통 항구 | "8080" |
| AWS_LWA_READINESS_CHECK_PORT / READINESS_CHECK_PORT* | 준비 확인 포트, 기본적으로 트래픽 포트 | 포트 |
| AWS_LWA_READINESS_CHECK_PATH / READINESS_CHECK_PATH* | 준비 상태 확인 경로 | "/" |
| AWS_LWA_READINESS_CHECK_PROTOCOL / READINESS_CHECK_PROTOCOL* | 준비 확인 프로토콜: "http" 또는 "tcp", 기본값은 "http" | "http" |
| AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS | 비정상으로 간주되는 최소 HTTP 상태 코드 | "500" |
| AWS_LWA_ASYNC_INIT / ASYNC_INIT* | 긴 초기화 기능에 대해 비동기 초기화 활성화 | "거짓" |
| AWS_LWA_REMOVE_BASE_PATH / REMOVE_BASE_PATH* | 요청 경로에서 제거할 기본 경로 | 없음 |
| AWS_LWA_ENABLE_COMPRESSION | 응답 본문에 대해 gzip 압축을 활성화합니다. | "거짓" |
| AWS_LWA_INVOKE_MODE | Lambda 함수 호출 모드: "buffered" 또는 "response_stream", 기본값은 "buffered"입니다. | "버퍼링됨" |
| AWS_LWA_PASS_THROUGH_PATH | http가 아닌 트리거에서 전달되는 이벤트 페이로드를 수신하기 위한 경로 | "/이벤트" |
| AWS_LWA_AUTHORIZATION_소스 | Authorization 으로 대체할 헤더 이름 | 없음 |
참고: Lambda Web Adaptor에서 사용하는 모든 환경 변수의 이름을 지정하기 위해 "AWS_LWA_" 접두사를 사용합니다. 원본 버전은 버전 1.0이 나올 때까지 지원됩니다.
AWS_LWA_PORT / PORT - Lambda 웹 어댑터가 이 포트로 트래픽을 보냅니다. 이는 웹 애플리케이션이 수신 대기하는 포트입니다. Lambda 실행 환경 내에서 웹 애플리케이션은 루트가 아닌 사용자로 실행되며 1024보다 낮은 포트에서는 수신 대기가 허용되지 않습니다. 포트 9001 및 3000도 피하십시오. Lambda 런타임 API는 포트 9001에 있습니다. CloudWatch Lambda Insight 확장은 포트 3000을 사용합니다. .
AWS_LWA_ASYNC_INIT / ASYNC_INIT - Lambda 관리형 런타임은 함수 초기화에 최대 10초를 제공합니다. 이 기간 동안 Lambda 함수는 초기화를 가속화하기 위해 CPU 버스트를 가지며 무료입니다. 람다 함수가 10초 이내에 초기화를 완료하지 못하면 Lambda는 함수를 다시 시작하고 초기화 비용을 청구합니다. 함수가 이 10초 무료 초기화 시간을 사용하고 다시 시작하는 것을 방지하기 위해 Lambda Web Adaptor는 비동기 초기화를 지원합니다. 이 기능이 활성화되면 Lambda 웹 어댑터는 최대 9.8초 동안 준비 상태 확인을 수행합니다. 그때까지 웹 앱이 준비되지 않으면 Lambda 웹 어댑터는 초기화가 완료되었음을 Lambda 서비스에 알리고 핸들러에서 준비 상태 확인을 계속합니다. 이 기능은 기본적으로 비활성화되어 있습니다. 환경 변수 AWS_LWA_ASYNC_INIT true 로 설정하여 활성화합니다.
AWS_LWA_REMOVE_BASE_PATH / REMOVE_BASE_PATH - 이 환경 변수의 값은 애플리케이션이 기본 경로에서 실행 중인지 여부를 어댑터에 알려줍니다. 예를 들어 /orders/{proxy+} 및 /catalog/{proxy+} 리소스를 갖도록 API 게이트웨이를 구성했을 수 있습니다. 각 리소스는 별도의 Lambda 함수에 의해 처리됩니다. 이러한 이유로 Lambda 내부의 애플리케이션은 /orders 경로가 존재한다는 사실을 인식하지 못할 수 있습니다. 요청을 애플리케이션으로 라우팅할 때 REMOVE_BASE_PATH를 사용하여 /orders 접두사를 제거합니다. 기본값은 빈 문자열입니다. SpringBoot 예제를 확인해 보세요.
AWS_LWA_ENABLE_COMPRESSION - Lambda 웹 어댑터는 응답 본문에 대해 gzip 압축을 지원합니다. 이 기능은 기본적으로 비활성화되어 있습니다. 환경 변수 AWS_LWA_ENABLE_COMPRESSION true 로 설정하여 활성화합니다. 활성화되면 image 로 시작하는 콘텐츠 유형에 따라 결정되는 이미지이거나 응답이 32바이트 미만이 아닌 한 응답을 압축합니다. 그러면 HTTP/1.1 청크 스트리밍 응답도 압축됩니다.
AWS_LWA_INVOKE_MODE - Lambda 함수 호출 모드. 이는 함수 Url 호출 모드와 일치해야 합니다. 기본값은 "버퍼링"입니다. "response_stream"으로 구성되면 Lambda 웹 어댑터는 Lambda 서비스 블로그에 응답을 스트리밍합니다. 응답 스트리밍 예제가 포함된 FastAPI를 확인해 보세요.
AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS - 정상으로 간주되는 HTTP 상태 코드와 그렇지 않은 HTTP 상태 코드를 사용자 정의할 수 있습니다.
AWS_LWA_PASS_THROUGH_PATH - http가 아닌 이벤트 트리거에서 전달된 이벤트 페이로드를 수신하는 경로입니다. 기본값은 "/이벤트"입니다.
AWS_LWA_AUTHORIZATION_SOURCE - 설정되면 Lambda 웹 어댑터는 요청을 프록시하기 전에 지정된 헤더 이름을 Authorization 으로 바꿉니다. 이는 IAM 인증을 위해 Authorization 헤더를 예약하는 IAM 인증 유형과 함께 Lambda 함수 URL을 사용하지만 백엔드 앱에는 Authorization 헤더를 계속 사용하려는 경우에 유용합니다. 이 기능은 기본적으로 비활성화되어 있습니다.
요청 컨텍스트 는 API 게이트웨이가 요청을 위해 Lambda로 보내는 메타데이터입니다. 일반적으로 requestId, requestTime, apiId, ID 및 승인자가 포함됩니다. ID 및 승인자는 승인을 위해 클라이언트 ID를 얻는 데 유용합니다. API 게이트웨이 개발자 가이드에는 여기에 자세한 내용이 포함되어 있습니다.
Lambda 웹 어댑터는 이 정보를 "x-amzn-request-context"라는 HTTP 헤더의 웹 애플리케이션에 전달합니다. 웹 애플리케이션에서 이 http 헤더의 값을 검색하고 이를 JSON 개체로 역직렬화할 수 있습니다. 사용 방법은 Zip의 Express.js를 확인하세요.
Lambda 컨텍스트 는 Lambda가 함수 핸들러에 전달하는 객체입니다. 이 객체는 호출, 함수, 실행 환경에 대한 정보를 제공합니다. 여기에서 Lambda 컨텍스트를 통해 액세스할 수 있는 전체 속성 목록을 찾을 수 있습니다.
Lambda 웹 어댑터는 이 정보를 "x-amzn-lambda-context"라는 HTTP 헤더의 웹 애플리케이션에 전달합니다. 웹 애플리케이션에서 이 http 헤더의 값을 검색하고 이를 JSON 개체로 역직렬화할 수 있습니다. 사용 방법은 Zip의 Express.js를 확인하세요.
Lambda 확장이 등록된 함수의 경우 Lambda는 함수에 대한 종료 단계를 활성화합니다. Lambda 서비스가 Lambda 실행 환경을 종료하려고 하면 SIGTERM 신호를 런타임에 보낸 다음 등록된 각 외부 확장 프로그램에 SHUTDOWN 이벤트를 보냅니다. 개발자는 람다 함수에서 SIGTERM 신호를 포착하고 정상적인 종료 작업을 수행할 수 있습니다. Express.js는 간단한 예를 제공합니다. 자세한 내용은 이 저장소에서 확인하세요.
Lambda 웹 어댑터를 사용하면 개발자는 익숙한 도구와 디버거를 사용하여 로컬에서 웹 애플리케이션을 개발할 수 있습니다. 웹 앱을 로컬에서 실행하고 테스트하기만 하면 됩니다. Lambda 런타임 환경을 로컬로 시뮬레이션하려면 AWS SAM CLI를 사용할 수 있습니다. 다음 명령은 로컬 API 게이트웨이 엔드포인트를 시작하고 Lambda 런타임 실행 환경을 시뮬레이션합니다.
sam local start-api sam local 포트 8080에서 Lambda 런타임 인터페이스 에뮬레이터를 시작합니다. 따라서 sam local 사용하려는 경우 웹 애플리케이션은 포트 8080 피해야 합니다.
Lambda 웹 어댑터는 SQS, SNS, S3, DynamoDB, Kinesis, Kafka, EventBridge 및 Bedrock 에이전트와 같은 HTTP가 아닌 모든 이벤트 트리거도 지원합니다. 어댑터는 AWS_LWA_PASS_THROUGH_PATH 환경 변수에 의해 정의된 경로에 대한 http 게시를 통해 웹 애플리케이션에 이벤트 페이로드를 전달합니다. 기본적으로 이 경로는 /events 로 설정됩니다. 요청 본문에서 이벤트 페이로드를 수신하면 웹 애플리케이션은 이를 처리하고 결과를 JSON 응답으로 반환해야 합니다. Zip 예제에서 SQS Express.js 및 Bedrock Agent FastAPI를 확인하세요.
이 프로젝트는 여러 커뮤니티 프로젝트에서 영감을 받았습니다.
몇몇 프로젝트는 언어별 패키지/프레임워크와 유사한 기능도 제공합니다.
자세한 내용은 기여를 참조하세요.
이 프로젝트는 Apache-2.0 라이선스에 따라 라이선스가 부여됩니다.
