# 컨테이너 이미지에 대한 SnapStart 후크 구현
<a name="snapstart-runtime-hooks-custom"></a>

## 개요
<a name="snapstart-custom-overview"></a>

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

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

## 사전 조건
<a name="snapstart-custom-prerequisites"></a>

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

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

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

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

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

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

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

## 수명 주기 개요
<a name="snapstart-custom-lifecycle"></a>

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

![SnapStart 사용자 지정 런타임의 Runtime API 호출 순서를 표시한 시퀀스 다이어그램. init, 스냅샷 이전 후크, GET/runtime/restore/next, 복원 이후 후크 및 표준 간접 호출 루프입니다.](https://docs.aws.amazon.com/ko_kr/lambda/latest/dg/images/snapstart-custom-runtime-lifecycle.png)


## SnapStart 수명 주기 후크 구현
<a name="snapstart-custom-implement"></a>

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가 스냅샷으로부터 실행 환경을 복원할 때까지 차단합니다.

1. **복원 이후 후크를 실행하고, 간접 호출 루프를 입력합니다.** `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
   ```

## 오류 처리
<a name="snapstart-custom-error-handling"></a>

후크가 실패하는 경우, 런타임은 해당 오류를 적절한 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 참조의 [초기화 오류](runtimes-api.md#runtimes-api-initerror) 및 [복원 오류(SnapStart에만 해당)](runtimes-api.md#runtimes-api-restore-error)를 참조하세요.