# 컨테이너 이미지를 사용하여 Lambda에 트랜스파일된 TypeScript 코드 배포
TypeScript 코드를 Node.js [컨테이너 이미지](images-create.md)로 AWS Lambda 함수에 배포할 수 있습니다. AWS는 컨테이너 이미지를 빌드하는 데 도움이 되는 Node.js용 [기본 이미지](nodejs-image.md#nodejs-image-base)를 제공합니다. 이러한 기본 이미지는 Lambda에서 이미지를 실행하는 데 필요한 언어 런타임 및 기타 구성 요소가 미리 로드되어 있습니다. AWS는 컨테이너 이미지를 빌드하는 데 도움이 되는 각 기본 이미지의 Dockerfile을 제공합니다.
커뮤니티 또는 사기업에서 제공하는 기본 이미지를 사용하는 경우 Lambda와 호환될 수 있도록 기본 이미지에 [Node.js 런타임 인터페이스 클라이언트(RIC)를 추가](nodejs-image.md#nodejs-image-clients)해야 합니다.
Lambda는 로컬 테스트를 위한 런타임 인터페이스 에뮬레이터를 제공합니다. Node.js용 AWS 기본 이미지에는 런타임 인터페이스 에뮬레이터가 포함되어 있습니다. Alpine Linux 또는 Debian 이미지와 같은 대체 기본 이미지를 사용하는 경우 [에뮬레이터를 이미지에 빌드](https://github.com/aws/aws-lambda-runtime-interface-emulator/?tab=readme-ov-file#build-rie-into-your-base-image)하거나 [로컬 시스템에 설치](https://github.com/aws/aws-lambda-runtime-interface-emulator/?tab=readme-ov-file#test-an-image-without-adding-rie-to-the-image)할 수 있습니다.
## Node.js 기본 이미지를 사용하여 TypeScript 함수 코드 빌드 및 패키징
### 사전 조건
이 섹션의 단계를 완료하려면 다음이 필요합니다.
+ [AWS CLI 버전 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [Docker](https://docs.docker.com/get-docker)(최소 버전 25.0.0)
+ Docker [buildx 플러그인](https://github.com/docker/buildx/blob/master/README.md)
+ Node.js 22.x
### 기본 이미지에서 이미지 생성
**Lambda용 AWS 기본 이미지에서 이미지를 생성하려면**
1. 로컬 컴퓨터에서 새 함수에 대한 프로젝트 디렉터리를 생성합니다.
1. 선택한 `npm` 또는 패키지 관리자를 사용하여 새 Node.js 프로젝트를 생성합니다.
```
npm init
```
1. [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) 및 [esbuild](https://esbuild.github.io/) 패키지를 개발 종속성으로 추가합니다. `@types/aws-lambda` 패키지에는 Lambda에 대한 유형 정의가 들어 있습니다.
```
npm install -D @types/aws-lambda esbuild
```
1. `package.json` 파일에 [빌드 스크립트](https://esbuild.github.io/getting-started/#build-scripts)를 추가합니다.
```
"scripts": {
"build": "esbuild index.ts --bundle --minify --sourcemap --platform=node --target=es2020 --outfile=dist/index.js"
}
```
1. `index.ts`라는 파일을 새로 생성합니다. 다음 샘플 코드를 새 파일에 추가합니다. Lambda 함수에 대한 코드입니다. 이 함수는 `hello world` 메시지를 반환합니다.
**참고**
`import` 문은 [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda)에서 유형 정의를 가져옵니다. 관련 없는 타사 도구인 `aws-lambda` NPM 패키지는 가져오지 않습니다. 자세한 내용은 DefinitelyTyped GitHub 리포지토리의 [aws-lambda](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/aws-lambda)를 참조하세요.
```
import { Context, APIGatewayProxyResult, APIGatewayEvent } from 'aws-lambda';
export const handler = async (event: APIGatewayEvent, context: Context): Promise => {
console.log(`Event: ${JSON.stringify(event, null, 2)}`);
console.log(`Context: ${JSON.stringify(context, null, 2)}`);
return {
statusCode: 200,
body: JSON.stringify({
message: 'hello world',
}),
};
};
```
1. 다음 구성으로 새 Dockerfile을 생성합니다.
+ `FROM` 속성을 기본 이미지의 URI로 설정합니다.
+ `CMD` 인수를 설정하여 Lambda 함수 핸들러를 지정합니다.
다음 예제 Dockerfile은 다단계 빌드를 사용합니다. 첫 번째 단계에서는 TypeScript 코드를 JavaScript로 트랜스파일합니다. 두 번째 단계에서는 JavaScript 파일 및 프로덕션 종속성만 포함하는 컨테이너 이미지를 생성합니다.
참고로 Dockerfile 예제에는 [USER 지침](https://docs.docker.com/reference/dockerfile/#user)이 포함되어 있지 않습니다. Lambda에 컨테이너 이미지를 배포할 때 Lambda는 권한이 최소 권한인 기본 Linux 사용자를 자동으로 정의합니다. 이는 `USER` 지침이 제공되지 않을 때 `root` 사용자에게 기본 설정이 적용되는 표준 Docker 동작과는 다릅니다.
**Example Dockerfile**
```
FROM public.ecr.aws/lambda/nodejs:22 as builder
WORKDIR /usr/app
COPY package.json index.ts ./
RUN npm install
RUN npm run build
FROM public.ecr.aws/lambda/nodejs:22
WORKDIR ${LAMBDA_TASK_ROOT}
COPY --from=builder /usr/app/dist/* ./
CMD ["index.handler"]
```
1. [docker build](https://docs.docker.com/engine/reference/commandline/build/) 명령으로 도커 이미지를 빌드합니다. 다음 예제에서는 이미지 이름을 `docker-image`로 지정하고 `test` [태그](https://docs.docker.com/engine/reference/commandline/build/#tag)를 지정합니다. 이미지를 Lambda와 호환되게 만들려면 `--provenance=false` 옵션을 사용해야 합니다.
```
docker buildx build --platform linux/amd64 --provenance=false -t docker-image:test .
```
**참고**
이 명령은 빌드 머신의 아키텍처에 관계없이 컨테이너가 Lambda 실행 환경과 호환되는지 확인하기 위해 `--platform linux/amd64` 옵션을 지정합니다. ARM64 명령 세트 아키텍처를 사용하여 Lambda 함수를 생성하려는 경우 `--platform linux/arm64` 옵션을 대신 사용하도록 명령을 변경해야 합니다.
### (선택 사항) 로컬에서 이미지 테스트
1. **docker run** 명령을 사용하여 Docker 이미지를 시작합니다. 이 예제에서 `docker-image`는 이미지 이름이고 `test`는 태그입니다.
```
docker run --platform linux/amd64 -p 9000:8080 docker-image:test
```
이 명령은 이미지를 컨테이너로 실행하고 `localhost:9000/2015-03-31/functions/function/invocations`에 로컬 엔드포인트를 생성합니다.
**참고**
ARM64 명령 세트 아키텍처를 위한 도커 이미지를 빌드한 경우 `--platform linux/arm64` 옵션을 `--platform linux/amd64` 대신 사용해야 합니다.
1. 새 터미널 창에서 로컬 엔드포인트에 이벤트를 게시합니다.
------
#### [ Linux/macOS ]
Linux 및 macOS에서 다음 `curl` 명령을 실행합니다.
```
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'
```
이 명령은 빈 이벤트와 함께 함수를 간접 호출하고 응답을 반환합니다. 샘플 함수 코드가 아닌 자체 함수 코드를 사용하는 경우 JSON 페이로드로 함수를 간접 호출할 수 있습니다. 예제:
```
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{"payload":"hello world!"}'
```
------
#### [ PowerShell ]
PowerShell에서 다음 `Invoke-WebRequest` 명령을 실행합니다.
```
Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{}' -ContentType "application/json"
```
이 명령은 빈 이벤트와 함께 함수를 간접 호출하고 응답을 반환합니다. 샘플 함수 코드가 아닌 자체 함수 코드를 사용하는 경우 JSON 페이로드로 함수를 간접 호출할 수 있습니다. 예제:
```
Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{"payload":"hello world!"}' -ContentType "application/json"
```
------
1. 컨테이너 ID를 가져옵니다.
```
docker ps
```
1. [docker kill](https://docs.docker.com/engine/reference/commandline/kill/) 명령을 사용하여 컨테이너를 중지합니다. 이 명령에서 `3766c4ab331c`를 이전 단계의 컨테이너 ID로 바꿉니다.
```
docker kill 3766c4ab331c
```
### 이미지 배포
**Amazon ECR에 이미지 배포 및 Lambda 함수 생성**
1. [get-login-password](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ecr/get-login-password.html) 명령을 실행하여 Amazon ECR 레지스트리에 대해 Docker CLI를 인증합니다.
+ `--region` 값을 Amazon ECR 리포지토리를 생성하려는 AWS 리전으로 설정합니다.
+ `111122223333`를 사용자의 AWS 계정 ID로 바꿉니다.
```
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.us-east-1.amazonaws.com
```
1. [create-repository](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ecr/create-repository.html) 명령을 사용하여 Amazon ECR에 리포지토리를 생성합니다.
```
aws ecr create-repository --repository-name hello-world --region us-east-1 --image-scanning-configuration scanOnPush=true --image-tag-mutability MUTABLE
```
**참고**
Amazon ECR 리포지토리는 Lambda 함수와 동일한 AWS 리전 내에 있어야 합니다.
성공하면 다음과 같은 응답이 표시됩니다.
```
{
"repository": {
"repositoryArn": "arn:aws:ecr:us-east-1:111122223333:repository/hello-world",
"registryId": "111122223333",
"repositoryName": "hello-world",
"repositoryUri": "111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world",
"createdAt": "2023-03-09T10:39:01+00:00",
"imageTagMutability": "MUTABLE",
"imageScanningConfiguration": {
"scanOnPush": true
},
"encryptionConfiguration": {
"encryptionType": "AES256"
}
}
}
```
1. 이전 단계의 출력에서 `repositoryUri`를 복사합니다.
1. [docker tag](https://docs.docker.com/engine/reference/commandline/tag/) 명령을 실행하여 로컬 이미지를 Amazon ECR 리포지토리에 최신 버전으로 태깅합니다. 이 명령에서:
+ `docker-image:test`는 Docker 이미지의 이름과 [태그](https://docs.docker.com/engine/reference/commandline/build/#tag)입니다. `docker build` 명령에서 지정한 이미지 이름 및 태그입니다.
+ ``를 복사한 `repositoryUri`로 바꿉니다. URI 끝에 `:latest`를 포함해야 합니다.
```
docker tag docker-image:test :latest
```
예제:
```
docker tag docker-image:test 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest
```
1. [docker push](https://docs.docker.com/engine/reference/commandline/push/) 명령을 실행하여 Amazon ECR 리포지토리에 로컬 이미지를 배포합니다. 리포지토리 URI 끝에 `:latest`를 포함해야 합니다.
```
docker push 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest
```
1. 함수에 대한 실행 역할이 아직 없는 경우 하나 [생성](lambda-intro-execution-role.md#permissions-executionrole-api)합니다. 다음 단계에서는 역할의 Amazon 리소스 이름(ARN)이 필요합니다.
1. Lambda 함수를 생성합니다. `ImageUri`의 경우 이전의 리포지토리 URI를 지정합니다. URI 끝에 `:latest`를 포함해야 합니다.
```
aws lambda create-function \
--function-name hello-world \
--package-type Image \
--code ImageUri=111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest \
--role arn:aws:iam::111122223333:role/lambda-ex
```
**참고**
이미지가 Lambda 함수와 동일한 리전에 있는 한 다른 AWS 계정의 이미지를 사용하여 함수를 생성할 수 있습니다. 자세한 내용은 [Amazon ECR 교차 계정 권한](images-create.md#configuration-images-xaccount-permissions) 섹션을 참조하세요.
1. 함수를 간접 호출합니다.
```
aws lambda invoke --function-name hello-world response.json
```
다음과 같은 응답이 표시되어야 합니다.
```
{
"ExecutedVersion": "$LATEST",
"StatusCode": 200
}
```
1. 함수의 출력을 보려면 `response.json` 파일을 확인합니다.
함수 코드를 업데이트하려면 이미지를 다시 빌드하고 Amazon ECR 리포지토리에 새 이미지를 업로드한 다음 [update-function-code](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-code.html) 명령을 사용하여 이미지를 Lambda 함수에 배포해야 합니다.
Lambda는 이미지 태그를 특정 이미지 다이제스트로 확인합니다. 즉, 함수를 배포하는 데 사용된 이미지 태그가 Amazon ECR의 새 이미지로 가리키는 경우 Lambda는 새 이미지를 사용하도록 함수를 자동으로 업데이트하지 않습니다.
새 이미지를 동일한 Lambda 함수에 배포하려면 Amazon ECR의 이미지 태그가 동일하게 유지되더라도 [update-function-code](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-code.html) 명령을 사용해야 합니다. 다음 예제에서 `--publish` 옵션은 업데이트된 컨테이너 이미지를 사용하여 새 버전의 함수를 생성합니다.
```
aws lambda update-function-code \
--function-name hello-world \
--image-uri 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest \
--publish
```