컨테이너 이미지를 위한 SnapStart 훅 구현하기

컨테이너 이미지를 위한 SnapStart 훅 구현하기

출처: AWS Lambda 개발자 안내서

본문

개요

컨테이너 이미지 함수와 함께 SnapStart를 사용할 때 런타임은 함수의 라이프사이클을 조정하고 적절한 라이프사이클 단계에서 스냅샷 이전(before-snapshot) 및 복원 이후(after-restore) 훅을 호출해야 해요. 이러한 훅을 사용하면 스냅샷 및 복원 라이프사이클의 지점에서 사용자 지정 로직(예: 자격 증명 새로 고침 또는 난수 생성기 재시드)을 실행할 수 있어요. SnapStart를 지원하는 관리형 런타임이나 해당 런타임의 기본 이미지(Java 버전 11+, Python 버전 3.12+, .NET 버전 8+)를 사용하면 Lambda가 라이프사이클을 조정해줘요. Lambda 함수 스냅샷 전후에 코드 구현에 설명된 API를 통해 훅을 등록하세요.

자체 기본 컨테이너 이미지, Runtime Interface Client(RIC) 또는 provided.al2023, Node.js, Ruby용 Lambda 기본 이미지를 사용한다면 이 페이지의 단계를 따라 SnapStart를 사용하세요.

사전 조건

Lambda가 스냅샷에서 함수를 복원할 때 초기화 중에 정의된 무작위 숫자 생성기, 고유 ID, 캐시된 자격 증명 같은 상태는 그 스냅샷에서 복원된 모든 실행 환경 간에 공유돼요. 컨테이너 이미지 기반 Lambda 함수와 함께 SnapStart를 사용하기 전에 Lambda SnapStart로 고유성 처리를 검토하고 암호학적으로 안전한 의사 난수 생성기(CSPRNG) 사용에 설명된 요구 사항이 충족되는지 확인하세요.

요구 사항이 충족되는지 검증한 후 다음 두 옵션 중 하나를 선택하세요.

  1. 옵션 1: 함수의 스냅샷이 재개될 때 사용자 지정 로직을 실행할 before-snapshot 및 after-restore 훅이 필요하다면 SnapStart 라이프사이클 훅 구현 섹션의 지침을 따르세요.

  2. 옵션 2: 이러한 훅이 필요하지 않다면 Dockerfile 내에서 다음 레이블을 지정하여 이 컨테이너 이미지에 SnapStart를 활성화하세요.

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

컨테이너 이미지가 /restore/next API를 구현하지도 않고 레이블도 포함하지 않으면 버전 게시가 실패해요.

참고(Note) 이러한 사전 조건은 Java(버전 11+), Python(버전 3.12+), .NET(버전 8+)용 Lambda 관리형 기본 이미지를 사용하면 필요하지 않아요. 이 이미지는 이미 SnapStart 라이프사이클을 조정하고 고유성 요구 사항을 제공하기 때문이에요.

라이프사이클 개요

다음 다이어그램은 SnapStart 사용자 지정 런타임이 호출할 것으로 예상되는 Runtime API 호출 순서를 보여줘요. 모든 호출은 Runtime API 계약의 일부이며, #3, #4, #5, #6 호출은 SnapStart에만 해당돼요.

SnapStart 라이프사이클 훅 구현

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

  1. before-snapshot 훅을 실행하고 스냅샷 프로세스를 트리거하세요: 함수의 초기화 코드의 마지막 단계로, 필요한 경우 before-snapshot 훅을 실행하고 스냅샷 프로세스를 트리거하세요. AWS_LAMBDA_INITIALIZATION_TYPE 환경 변수의 값이 snap-start로 설정되어 있는지 확인해서 SnapStart가 활성화된 경우에만 이러한 단계를 수행하세요. 등록된 before-snapshot 훅을 실행한 다음 GET /runtime/restore/next를 호출해서 스냅샷 프로세스를 트리거하세요. before-snapshot 훅이 예외를 던지거나 오류를 반환하면 런타임은 /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

참고(Note) 초기화 단계와 before-snapshot 훅은 max(function_timeout, 130 seconds)의 결합 타임아웃을 공유해요. 이 제한을 초과하면 Lambda가 PublishVersion 요청을 실패시켜요. 또한 /runtime/invocation/next와 마찬가지로 /runtime/restore/next 호출은 블로킹 호출이에요. Lambda가 스냅샷에서 실행 환경을 복원할 때까지 블록된 상태로 있다가 HTTP 200을 반환해요.

  1. after-restore 훅을 실행한 다음 호출 루프에 진입하세요. GET /runtime/restore/next가 200을 반환하면 런타임은 호출 루프로 진행하기 전에 등록된 after-restore 훅을 실행해야 해요. after-restore 훅이 실패하면 /runtime/restore/error에 오류를 보고하세요. after-restore 훅이 완료되면 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
       GET /runtime/invocation/next

오류 처리

훅이 실패하면 런타임은 적절한 API 엔드포인트에 오류를 보고하고 프로세스를 종료해야 해요. 아래 표는 각 단계의 동작을 요약해요.

단계 오류 API 엔드포인트 실패 시 동작
Init / before-snapshot POST /runtime/init/error Lambda가 PublishVersion 요청을 실패시켜요. 프로세스를 종료해요.
After-restore POST /runtime/restore/error Lambda가 진행 중인 호출을 실패시키고 실행 환경을 분해해요. 프로세스를 종료해요.

두 API 엔드포인트 모두에 대해 Lambda-Runtime-Function-Error-Type 헤더를 <Category.Reason> 형식(예: Runtime.BeforeSnapshotError 또는 Runtime.AfterRestoreError)의 값으로 설정하세요. errorMessage, errorType, 선택적 stackTrace가 포함된 오류 본문을 포함하세요.

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

더 알아보기 (Learn more)

SnapStart에 대한 자세한 내용은 Lambda SnapStart를 참고하세요.