.zip 파일 아카이브로 컴파일된(TypeScript) 코드를 Lambda에 배포하기

.zip 파일 아카이브로 컴파일된(TypeScript) 코드를 Lambda에 배포하기 (Deploy transpiled TypeScript code in Lambda with .zip file archives)

TypeScript 코드를 AWS Lambda에 배포하려면 먼저 JavaScript로 컴파일(transpile)해야 해요. 이 페이지에서는 .zip 파일 아카이브로 TypeScript 코드를 Lambda에 빌드하고 배포하는 세 가지 방법을 설명해요.

• AWS Serverless Application Model(AWS SAM) 사용
• AWS Cloud Development Kit(AWS CDK) 사용
• AWS Command Line Interface(AWS CLI)와 esbuild 사용

AWS SAM과 AWS CDK는 TypeScript 함수의 빌드와 배포를 간단하게 만들어줘요. AWS SAM 템플릿 사양(specification)은 서버리스 애플리케이션을 구성하는 Lambda 함수, API, 권한, 구성, 이벤트를 설명하는 간단하고 깔끔한 문법을 제공해요. AWS CDK로는 프로그래밍 언어의 상당한 표현력을 활용해 클라우드에서 안정적이고 확장 가능하며 비용 효율적인 애플리케이션을 만들 수 있어요. AWS CDK는 AWS에 중간~고급 경험이 있는 사용자를 대상으로 해요. AWS CDK와 AWS SAM 모두 esbuild를 사용해 TypeScript 코드를 JavaScript로 컴파일해요.

출처: AWS Lambda 개발자 안내서

본문

AWS SAM으로 TypeScript 코드를 Lambda에 배포하기

아래 단계에 따라 AWS SAM으로 샘플 Hello World TypeScript 애플리케이션을 다운로드하고 빌드한 뒤 배포할 수 있어요. 이 애플리케이션은 기본 API 백엔드를 구현해요. Amazon API Gateway 엔드포인트와 Lambda 함수로 구성되죠. API Gateway 엔드포인트에 GET 요청을 보내면 Lambda 함수가 호출되고, 함수는 hello world 메시지를 반환해요.

참고 AWS SAM은 esbuild로 TypeScript 코드에서 Node.js Lambda 함수를 만들어요. esbuild 지원은 현재 공개 미리보기(public preview) 상태예요. 공개 미리보기 동안에는 esbuild 지원에 이전 버전과 호환되지 않는 변경이 있을 수 있어요.

전제 조건

이 섹션의 단계를 완료하려면 다음이 필요해요.

• AWS CLI version 2
• AWS SAM CLI version 1.75 이상
• Node.js

샘플 AWS SAM 애플리케이션 배포하기

1. Hello World TypeScript 템플릿으로 애플리케이션을 초기화해요.

sam init --app-template hello-world-typescript --name sam-app --package-type Zip --runtime nodejs24.x

2. (선택 사항) 샘플 애플리케이션에는 코드 린팅용 ESLint, 단위 테스트용 Jest 같은 자주 쓰이는 도구용 구성이 포함돼 있어요. 린트와 테스트 명령을 실행하려면:

cd sam-app/hello-world
npm install
npm run lint
npm run test

3. 앱을 빌드해요.

cd sam-app
sam build

4. 앱을 배포해요.

sam deploy --guided

5. 화면의 프롬프트를 따라가요. 인터랙티브 환경에서 제공되는 기본 옵션을 받아들이려면 Enter로 응답해요.

6. 출력에 REST API용 엔드포인트가 표시돼요. 브라우저에서 엔드포인트를 열어 함수를 테스트해요. 다음 응답이 보일 거예요.

{"message":"hello world"}

7. 이건 인터넷을 통해 접근할 수 있는 공개 API 엔드포인트예요. 테스트가 끝나면 엔드포인트를 삭제하는 걸 권장해요.

sam delete

AWS CDK로 TypeScript 코드를 Lambda에 배포하기

아래 단계에 따라 AWS CDK로 샘플 TypeScript 애플리케이션을 빌드하고 배포할 수 있어요. 이 애플리케이션은 기본 API 백엔드를 구현해요. API Gateway 엔드포인트와 Lambda 함수로 구성되죠. API Gateway 엔드포인트에 GET 요청을 보내면 Lambda 함수가 호출되고, 함수는 hello world 메시지를 반환해요.

전제 조건

이 섹션의 단계를 완료하려면 다음이 필요해요.

• AWS CLI version 2
• AWS CDK version 2
• Node.js
• Docker 또는 esbuild 중 하나

샘플 AWS CDK 애플리케이션 배포하기

1. 새 애플리케이션용 프로젝트 디렉터리를 만들어요.

mkdir hello-world
cd hello-world

2. 앱을 초기화해요.

cdk init app --language typescript

3. @types/aws-lambda 패키지를 개발 의존성으로 추가해요. 이 패키지에는 Lambda용 타입 정의가 들어 있어요.

npm install -D @types/aws-lambda

4. lib 디렉터리를 열면 hello-world-stack.ts 파일이 보여요. 이 디렉터리에 hello-world.function.ts와 hello-world.ts 두 파일을 새로 만들어요.

5. hello-world.function.ts를 열고 파일에 다음 코드를 추가해요. 이건 Lambda 함수용 코드예요.

참고 import 문은 @types/aws-lambda에서 타입 정의를 가져와요. 관련 없는 서드파티 도구인 aws-lambda NPM 패키지를 가져오는 게 아니에요. 자세한 내용은 DefinitelyTyped GitHub 저장소의 aws-lambda를 참고하세요.

import { Context, APIGatewayProxyResult, APIGatewayEvent } from 'aws-lambda';

export const handler = async (
  event: APIGatewayEvent,
  context: Context
): Promise<APIGatewayProxyResult> => {
  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',
    }),
  };
};

6. hello-world.ts를 열고 파일에 다음 코드를 추가해요. 여기에는 Lambda 함수를 만드는 NodejsFunction construct와 REST API를 만드는 LambdaRestApi construct가 들어 있어요.

import { Construct } from 'constructs';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
import { LambdaRestApi } from 'aws-cdk-lib/aws-apigateway';

export class HelloWorld extends Construct {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    const helloFunction = new NodejsFunction(this, 'function');
    new LambdaRestApi(this, 'apigw', {
      handler: helloFunction,
    });
  }
}

NodejsFunction construct는 기본적으로 다음을 가정해요. 함수 핸들러의 이름이 handler라는 점, 함수 코드가 담긴 .ts 파일(hello-world.function.ts)이 construct가 담긴 .ts 파일(hello-world.ts)과 같은 디렉터리에 있다는 점이에요. construct는 construct의 ID("hello-world")와 Lambda 핸들러 파일 이름("function")으로 함수 코드를 찾아요. 예를 들어 함수 코드가 hello-world.my-function.ts 파일에 있다면 hello-world.ts 파일은 함수 코드를 다음과 같이 참조해야 해요.

const helloFunction = new NodejsFunction(this, 'my-function');

이 동작을 바꾸고 다른 esbuild 파라미터를 구성할 수도 있어요. 자세한 내용은 AWS CDK API 레퍼런스의 Configuring esbuild를 참고하세요.

7. hello-world-stack.ts를 열어요. 이건 AWS CDK 스택(stack)을 정의하는 코드예요. 코드를 다음으로 교체해요.

import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { HelloWorld } from './hello-world';

export class HelloWorldStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    new HelloWorld(this, 'hello-world');
  }
}

8. cdk.json 파일이 있는 hello-world 디렉터리에서 애플리케이션을 배포해요.

cdk deploy

9. AWS CDK가 esbuild로 Lambda 함수를 빌드·패키징한 다음 Lambda 런타임에 배포해요. 출력에 REST API용 엔드포인트가 표시돼요. 브라우저에서 엔드포인트를 열어 함수를 테스트해요. 다음 응답이 보일 거예요.

{"message":"hello world"}

이건 인터넷을 통해 접근할 수 있는 공개 API 엔드포인트예요. 테스트가 끝나면 엔드포인트를 삭제하는 걸 권장해요.

AWS CLI와 esbuild로 TypeScript 코드를 Lambda에 배포하기

다음 예시는 esbuild와 AWS CLI로 TypeScript 코드를 Lambda에 컴파일하고 배포하는 방법을 보여줘요. esbuild는 모든 의존성과 함께 JavaScript 파일 하나를 만들어요. .zip 아카이브에 추가해야 하는 파일은 이 파일 하나뿐이에요.

전제 조건

이 섹션의 단계를 완료하려면 다음이 필요해요.

• AWS CLI version 2
• Node.js
• Lambda 함수용 실행 역할(execution role)
• Windows 사용자는 7zip 같은 zip 파일 유틸리티

샘플 함수 배포하기

1. 로컬 머신에서 새 함수용 프로젝트 디렉터리를 만들어요.
2. npm이나 원하는 패키지 매니저로 새 Node.js 프로젝트를 만들어요.

npm init

3. @types/aws-lambda와 esbuild 패키지를 개발 의존성으로 추가해요. @types/aws-lambda 패키지에는 Lambda용 타입 정의가 들어 있어요.

npm install -D @types/aws-lambda esbuild

4. index.ts라는 새 파일을 만들어요. 새 파일에 다음 코드를 추가해요. 이건 Lambda 함수용 코드예요. 함수는 hello world 메시지를 반환해요. 함수는 API Gateway 리소스를 만들지 않아요.

참고 import 문은 @types/aws-lambda에서 타입 정의를 가져와요. 관련 없는 서드파티 도구인 aws-lambda NPM 패키지를 가져오는 게 아니에요. 자세한 내용은 DefinitelyTyped GitHub 저장소의 aws-lambda를 참고하세요.

import { Context, APIGatewayProxyResult, APIGatewayEvent } from 'aws-lambda';

export const handler = async (
  event: APIGatewayEvent,
  context: Context
): Promise<APIGatewayProxyResult> => {
  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',
    }),
  };
};

5. package.json 파일에 빌드 스크립트를 추가해요. 이 스크립트는 esbuild가 .zip 배포 패키지를 자동으로 만들도록 구성해요. 자세한 내용은 esbuild 문서의 Build scripts를 참고하세요.

Linux와 MacOS:

"scripts": {
  "prebuild": "rm -rf dist",
  "build": "esbuild index.ts --bundle --minify --sourcemap --platform=node --target=es2020 --outfile=dist/index.js",
  "postbuild": "cd dist && zip -r index.zip index.js*"
},

Windows:

이 예시에서 "postbuild" 명령은 7zip 유틸리티로 .zip 파일을 만들어요. 원하는 Windows zip 유틸리티를 사용하고 명령을 필요에 맞게 수정하세요.

"scripts": {
  "prebuild": "del /q dist",
  "build": "esbuild index.ts --bundle --minify --sourcemap --platform=node --target=es2020 --outfile=dist/index.js",
  "postbuild": "cd dist && 7z a -tzip index.zip index.js*"
},

6. 패키지를 빌드해요.

npm run build

7. .zip 배포 패키지로 Lambda 함수를 만들어요. 강조 표시된 텍스트를 여러분 실행 역할의 Amazon Resource Name(ARN)으로 바꿔요.

aws lambda create-function --function-name hello-world \
--runtime "nodejs24.x" --role arn:aws:iam::123456789012:role/lambda-ex \
--zip-file "fileb://dist/index.zip" --handler index.handler

8. 테스트 이벤트 실행하기로 함수가 다음 응답을 반환하는지 확인해요. API Gateway로 이 함수를 호출하려면 REST API를 만들고 구성하세요.

{
  "statusCode": 200,
  "body": "{\"message\":\"hello world\"}"
}

더 알아보기 (Learn more)

• Node.js Lambda 함수 배포
• 실행 역할