컨테이너 이미지에 대한 SnapStart 후크 구현

개요

SnapStart를 컨테이너 이미지 함수와 함께 사용하는 경우, 런타임이 함수의 수명 주기를 조율하고 적절한 수명 주기 단계 동안 스냅샷 이전 후크와 복원 이후 후크를 호출해야 합니다. 이러한 후크를 사용하면 스냅샷-복원 수명 주기 중 여러 지점에서 사용자 지정 로직(예: 자격 증명 새로 고침 또는 난수 생성기 다시 시드)을 실행할 수 있습니다. SnapStart가 지원되는 관리형 런타임 또는 그러한 런타임에 상응하는 기본 이미지(Java 버전 11+, Python 버전 3.12+, .NET 버전 8+)를 사용하는 경우, Lambda가 대신 수명 주기를 조율해 줍니다. Lambda 함수 스냅샷 전후 코드 구현에 설명된 API를 통해 후크를 등록합니다.

자체 기본 컨테이너 이미지, 런타임 인터페이스 클라이언트(RIC) 또는 Lambda의 provided.al2023, Node.js 또는 Ruby용 기본 이미지를 사용하는 경우, 이 페이지의 단계를 따라 SnapStart를 사용하세요.

사전 조건

Lambda가 스냅샷으로부터 함수를 복원하면 초기화 중에 정의된 모든 상태(예: 난수 생성기, 고유한 ID 및 캐싱된 자격 증명)가 해당 스냅샷에서 복원된 모든 실행 환경에서 공유됩니다. SnapStart를 컨테이너 이미지 기반 Lambda 함수와 함께 사용하기 전에 Lambda SnapStart를 사용한 고유성 처리를 검토하고 암호학적으로 안전한 가상 난수 생성기(CSPRNG) 사용에 개괄된 요구 사항을 충족하는지 확인하세요.

요구 사항을 충족하는지 검증한 후, 다음 두 가지 옵션 중 하나를 선택합니다.

1. 옵션 1: 함수의 스냅샷이 재개된 이후 사용자 지정 로직을 실행하는 데 스냅샷 이전 및 복원 이후 후크가 필요한 경우, 섹션 SnapStart 수명 주기 후크 구현의 지침을 따릅니다.

2. 옵션 2: 그러한 후크가 필요하지 않은 경우, Dockerfile 내에서 다음 라벨을 지정해 이 컨테이너 이미지에 대해 SnapStart를 활성화합니다.

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

컨테이너 이미지가 /restore/next API를 구현하지 못하고 라벨을 포함하지 못하면 버전 게시가 실패합니다.

참고

이러한 사전 조건은 Java(버전 11+), Python(버전 3.12+) 및 .NET(버전 8+)용 Lambda 관리형 기본 이미지를 사용하는 경우에는 필요하지 않습니다. 해당 기본 이미지는 이미 SnapStart 수명 주기를 조율하고 고유성 요구 사항을 제공하기 때문입니다.

수명 주기 개요

다음 다이어그램은 SnapStart 사용자 지정 런타임이 할 것으로 예상되는 Runtime API 호출 순서를 표시한 것입니다. 모든 호출이 Runtime API 계약에 속하지만, 호출 #3, #4, #5, #6은 SnapStart에만 한정됩니다.

SnapStart 수명 주기 후크 구현

SnapStart를 컨테이너 이미지 함수와 함께 사용하려면 다음 단계를 따르세요.

1. 스냅샷 이전 후크를 실행하고 스냅샷 프로세스 트리거: 함수의 초기화 코드 마지막 단계로, 필요한 경우 스냅샷 이전 후크를 실행하고 스냅샷 프로세스를 트리거합니다. 이러한 단계는 AWS_LAMBDA_INITIALIZATION_TYPE 환경 변수의 값이 snap-start로 설정되었는지 확인해 SnapStart가 활성화되어 있는 경우에만 수행하세요. 등록된 스냅샷 이전 후크를 실행한 다음 GET /runtime/restore/next를 호출해 스냅샷 프로세스를 트리거합니다. 스냅샷 이전 후크가 오류를 발생시키거나 반환하는 경우, 런타임이 /runtime/init/error 엔드포인트에 해당 오류를 게시합니다. 아래의 유사 코드 샘플을 참조하세요.

   # 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

   참고

   init 단계와 스냅샷 이전 후크는 합산된 시간 제한 max(function_timeout, 130 seconds)를 공유합니다. 이 한도가 초과되면 Lambda가 PublishVersion 요청에 실패합니다. 또한 /runtime/restore/next 호출은 /runtime/invocation/next와 마찬가지로 차단 호출입니다. 이 호출은 Lambda가 스냅샷으로부터 실행 환경을 복원할 때까지 차단합니다.

2. 복원 이후 후크를 실행하고, 간접 호출 루프를 입력합니다. GET /runtime/restore/next가 200을 반환하면 런타임이 등록된 복원 이후 후크를 실행한 다음에만 간접 호출 루프로 계속 진행해야 합니다. 복원 이후 후크가 실패하면 오류를 /runtime/restore/error에 보고합니다. 복원 이후 후크가 완료된 후, GET /runtime/invocation/next를 호출해 표준 간접 호출 루프를 입력합니다. 이 시점 이후부터는 동작이 SnapStart를 사용하지 않는 함수와 똑같습니다. 아래의 유사 코드 샘플을 참조하세요.

   # 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

오류 처리

후크가 실패하는 경우, 런타임은 해당 오류를 적절한 API 엔드포인트에 보고하고 프로세스를 종료해야 합니다. 아래 표에 각 단계의 동작을 요약했습니다.

단계	오류 API 엔드포인트	실패 시 발생하는 일
Init/스냅샷 이전	POST /runtime/init/error	Lambda가 PublishVersion 요청에 실패합니다. 프로세스를 종료합니다.
복원 이후	POST /runtime/restore/error	Lambda는 진행 중인 호출을 실패 처리하고 실행 환경을 해체합니다. 프로세스를 종료합니다.

두 API 엔드포인트 모두에 대해 Lambda-Runtime-Function-Error-Type 헤더를 <Category.Reason> 형식의 값으로 설정합니다(예: Runtime.BeforeSnapshotError 또는 Runtime.AfterRestoreError). 오류 본문과 errorMessage, errorType 및 선택 사항으로 stackTrace를 포함합니다.

API 엔드포인트 사양 및 응답 코드 전문은 Runtime API 참조의 초기화 오류 및 복원 오류(SnapStart에만 해당)를 참조하세요.