Serverless Framework로 AWS Lambda API 구축: 시작부터 배포까지 완벽 가이드

Serverless Framework를 활용하여 AWS Lambda 기반의 REST API를 쉽고 빠르게 구축하고 배포하는 과정을 상세히 안내합니다. 복잡한 클라우드 설정 없이 효율적인 개발을 경험해보세요.

혹시 서비스 개발을 꿈꾸면서도 서버 관리의 복잡함 때문에 망설여본 적 있으신가요? 아니면 이미 운영 중인 서비스의 트래픽 급증에 대한 걱정이나 유지보수 비용 때문에 고민이 많으셨나요? 만약 그렇다면, 서버리스(Serverless) 아키텍처가 여러분의 고민을 덜어줄 아주 매력적인 대안이 될 수 있습니다. 서버리스는 말 그대로 '서버가 없다'는 뜻이 아니라, 개발자가 서버를 직접 관리할 필요 없이 서비스 코드 작성에만 집중할 수 있도록 클라우드 공급자가 모든 인프라를 대신 관리해주는 방식이거든요.

이 글에서는 특히 AWS의 Lambda와 API Gateway를 활용하여 강력한 API를 구축하고, 이 모든 과정을 Serverless Framework라는 도구를 통해 어떻게 쉽고 효율적으로 자동화할 수 있는지 상세히 알아보려고 합니다. 복잡한 클라우드 설정은 잠시 잊고, 여러분의 아이디어를 빠르게 현실로 만들 수 있는 서버리스의 세계로 함께 떠나볼까요?

📑 목차

• 서버리스 아키텍처, 왜 주목할까요?
• 전통적인 서버 방식과의 차이점
• Serverless Framework, 당신의 서버리스 조력자
• 개발 환경 설정: 첫걸음 떼기
• 1. Node.js 설치
• 2. AWS CLI 설정
• 3. Serverless Framework 설치
• AWS Lambda API 구축: Hello, Serverless!
• 1. 새 서버리스 프로젝트 생성
• 2. `serverless.yml` 파일 설정
• 3. `handler.js` 파일 작성
• API 배포 및 관리: 실제 서비스처럼
• 1. 서버리스 API 배포
• 2. API 업데이트 및 로그 확인
• 3. 배포된 API 제거
• 실전 팁과 고려사항: 더 나은 서버리스를 위해
• 1. 환경 변수 활용
• 2. 콜드 스타트(Cold Start) 이해 및 최적화
• 3. 로컬 개발 및 테스트
• 4. 보안 강화
• 마무리하며: 서버리스, 이제 당신의 차례입니다!

Image by bottomlayercz0 on Pixabay

서버리스 아키텍처, 왜 주목할까요?

서버리스라는 단어를 들으면 '서버가 없다고? 그럼 어떻게 동작해?'라는 의문이 들 수 있어요. 사실 서버는 늘 존재하죠. 다만, 그 서버의 프로비저닝, 패치, 스케일링, 관리 등 번거로운 작업들을 클라우드 공급자가 대신 처리해준다는 의미입니다. 개발자는 오로지 비즈니스 로직을 담은 코드만 작성하고 배포하면 되니, 개발 생산성이 엄청나게 향상될 수 있습니다.

서버리스 아키텍처가 가져다주는 핵심적인 이점들은 다음과 같습니다.

• 운영 부담 감소: 서버 관리, OS 패치, 보안 업데이트 등 인프라 운영에 드는 시간과 노력을 최소화할 수 있습니다. 개발팀은 핵심 서비스 개발에만 집중할 수 있게 되죠.
• 자동 스케일링: 트래픽이 폭증해도 걱정 마세요. 클라우드 서비스가 알아서 필요한 만큼 자원을 확장해주기 때문에, 별도의 설정 없이도 안정적인 서비스를 제공할 수 있습니다. 반대로 트래픽이 없을 때는 자원을 축소하여 비용 효율을 높입니다.
• 비용 효율성: 사용한 만큼만 비용을 지불하는 종량제(Pay-per-use) 모델입니다. 함수가 실행된 시간(밀리초 단위)과 메모리 사용량에 따라 과금되므로, 유휴 자원에 대한 불필요한 비용 지출이 없습니다. 예를 들어, 한 달에 100만 번 호출되고 각 호출당 100ms가 소요되는 256MB 람다 함수는 대략 2~3달러 수준의 비용이 발생할 수 있습니다.
• 빠른 개발 및 배포: 인프라 구축 및 설정에 드는 시간이 줄어들어, 아이디어를 빠르게 구현하고 시장에 출시할 수 있습니다. 이는 MVP(Minimum Viable Product) 개발에 특히 유리하죠.

전통적인 서버 방식과의 차이점

서버리스가 왜 이렇게 매력적인지, 기존 방식과 비교해보면 더욱 명확해집니다.

특징	전통적인 서버(VM, 컨테이너)	서버리스(AWS Lambda)
서버 관리	개발팀이 직접 OS, 런타임, 보안 패치 등 관리	클라우드 공급자가 모두 관리, 개발자는 코드만 작성
스케일링	수동 설정 또는 복잡한 자동 스케일링 정책 필요	트래픽에 따라 자동으로 확장/축소
비용 모델	서버 가동 시간 기반, 유휴 시간에도 비용 발생	실제 함수 실행 시간 및 자원 사용량 기반 (종량제)
배포 단위	애플리케이션 전체 또는 컨테이너 이미지	개별 함수(Function) 단위
시작 시간	항상 가동 중이므로 즉시 응답	콜드 스타트(Cold Start) 가능성 존재

물론 콜드 스타트와 같은 단점도 존재하지만, 대부분의 웹 API나 이벤트 기반 서비스에서는 그 이점이 훨씬 크다고 평가받고 있습니다.

Serverless Framework, 당신의 서버리스 조력자

AWS Lambda, API Gateway 등 다양한 서버리스 서비스를 수동으로 설정하는 건 생각보다 번거롭고 복잡한 일입니다. 수많은 콘솔 클릭과 YAML 설정 파일들을 일일이 관리하는 건 쉬운 일이 아니죠. 이때 Serverless Framework가 구세주처럼 등장합니다! Serverless Framework는 YAML 기반의 선언적 설정을 통해 여러 클라우드 공급자의 서버리스 리소스를 통합적으로 관리하고 배포할 수 있도록 돕는 오픈소스 CLI(Command Line Interface) 도구입니다.

주요 특징은 다음과 같습니다.

• 인프라를 코드로(IaC, Infrastructure as Code): `serverless.yml` 파일 하나로 Lambda 함수, API Gateway 엔드포인트, IAM 권한, S3 버킷 등 필요한 모든 AWS 리소스를 정의하고 관리할 수 있습니다. 이는 버전 관리와 협업에 매우 유리하죠.
• 멀티 클라우드 지원: AWS뿐만 아니라 Google Cloud Functions, Azure Functions 등 다양한 클라우드 공급자를 지원하여, 특정 벤더에 종속되지 않는 유연성을 제공합니다.
• 확장 가능한 플러그인 생태계: 로컬 개발, 배포 최적화, 모니터링 연동 등 다양한 기능을 플러그인을 통해 손쉽게 추가할 수 있습니다.
• 간편한 배포 및 관리: 단 몇 줄의 명령어로 서버리스 애플리케이션을 배포하고, 업데이트하고, 삭제할 수 있습니다.

개발 환경 설정: 첫걸음 떼기

이제 Serverless Framework를 사용하기 위한 개발 환경을 설정해볼까요? 크게 세 가지 단계를 거칩니다.

1. Node.js 설치

Serverless Framework는 Node.js 기반으로 동작하며, 대부분의 AWS Lambda 함수도 Node.js 런타임을 사용합니다. 따라서 Node.js를 먼저 설치해야 합니다. Node.js 공식 홈페이지에서 LTS(Long Term Support) 버전을 다운로드하여 설치하는 것을 권장합니다. 설치 후 터미널에서 다음 명령어로 버전을 확인해보세요.

node -v
npm -v

정상적으로 버전 정보가 출력되면 설치가 완료된 겁니다.

2. AWS CLI 설정

Serverless Framework는 AWS 리소스를 생성하고 관리하기 위해 AWS CLI(Command Line Interface)를 사용합니다. AWS CLI를 설치하고, 여러분의 AWS 계정에 접근할 수 있는 자격 증명(Credential)을 설정해야 합니다.

1. AWS CLI 설치: AWS CLI 공식 문서를 참고하여 OS에 맞는 버전을 설치합니다.
2. IAM 사용자 생성 및 권한 부여: AWS 콘솔에 접속하여 IAM(Identity and Access Management) 서비스로 이동합니다. 새로운 사용자를 생성하고, 프로그래밍 방식 액세스(Programmatic access)를 허용합니다. 이 사용자에게는 AWSLambda_FullAccess, AmazonAPIGatewayAdministrator, IAMFullAccess, AmazonS3FullAccess, CloudWatchFullAccess 등의 정책을 부여하여 Serverless Framework가 필요한 리소스를 생성하고 관리할 수 있도록 합니다. 실제 운영 환경에서는 최소 권한의 원칙(Principle of Least Privilege)에 따라 더 세분화된 권한을 부여하는 것이 좋습니다.
3. 자격 증명 설정: IAM 사용자 생성 후 발급받은 액세스 키 ID(Access Key ID)와 비밀 액세스 키(Secret Access Key)를 사용하여 AWS CLI를 설정합니다.

aws configure
AWS Access Key ID [None]: YOUR_ACCESS_KEY_ID
AWS Secret Access Key [None]: YOUR_SECRET_ACCESS_KEY
Default region name [None]: ap-northeast-2 (예: 서울 리전)
Default output format [None]: json

이렇게 설정하면 Serverless Framework가 AWS와 통신할 준비가 끝납니다.

3. Serverless Framework 설치

Node.js와 AWS CLI가 준비되었다면, 이제 Serverless Framework를 전역으로 설치합니다.

npm install -g serverless

설치가 완료되면 다음 명령어로 버전을 확인하여 정상 설치 여부를 확인합니다.

sls -v
# 또는
serverless -v

이제 모든 준비가 끝났습니다! 정말 간단하죠?

Image by onkelglocke on Pixabay

AWS Lambda API 구축: Hello, Serverless!

이제 Serverless Framework를 사용하여 간단한 API를 구축해볼 차례입니다. "Hello, Serverless!"를 출력하는 API를 만들어보겠습니다.

1. 새 서버리스 프로젝트 생성

먼저 새로운 서버리스 프로젝트를 생성합니다. `sls create` 명령어를 사용하며, 템플릿과 프로젝트 이름을 지정할 수 있습니다.

sls create --template aws-nodejs --path my-serverless-api
cd my-serverless-api

위 명령어는 `my-serverless-api`라는 디렉토리를 생성하고, 그 안에 AWS Node.js 템플릿 기반의 초기 파일들을 생성합니다. 생성된 파일들을 살펴보면 다음과 같습니다.

• `serverless.yml`: 서버리스 애플리케이션의 핵심 설정 파일입니다. 서비스 이름, 클라우드 공급자, 함수, 이벤트 등을 정의합니다.
• `handler.js`: Lambda 함수의 실제 코드가 들어가는 파일입니다.
• `.gitignore`: Git 버전 관리에서 제외할 파일들을 정의합니다.

2. `serverless.yml` 파일 설정

`serverless.yml` 파일을 열어보면 이미 기본적인 내용이 채워져 있을 겁니다. 우리는 여기에 API Gateway 이벤트를 추가하여 HTTP 요청을 처리하도록 만들 거예요.

# serverless.yml
service: my-serverless-api # 서비스 이름 (AWS CloudFormation 스택 이름에 사용됩니다)

frameworkVersion: '3' # Serverless Framework 버전 지정

provider:
  name: aws
  runtime: nodejs18.x # Lambda 함수의 런타임 (Node.js 18 버전)
  region: ap-northeast-2 # 배포할 AWS 리전
  stage: dev # 배포 단계 (개발, 스테이징, 프로덕션 등으로 구분)
  
functions:
  hello: # 함수 이름
    handler: handler.hello # handler.js 파일의 hello 함수를 실행
    events:
      - http: # HTTP 이벤트를 정의 (API Gateway를 통해 호출 가능)
          path: hello # API Gateway 경로 (예: /hello)
          method: get # HTTP 메서드 (GET 요청)

간단히 설명하자면:

• `service`: 이 서버리스 애플리케이션의 고유한 이름입니다.
• `provider`: 클라우드 공급자를 AWS로 지정하고, Node.js 18 런타임, 서울 리전(`ap-northeast-2`), 개발 스테이지(`dev`)를 설정했습니다.
• `functions`: 여기에 Lambda 함수들을 정의합니다.
  • `hello`: 이 함수의 이름입니다.
  • `handler`: `handler.js` 파일 안에 있는 `hello`라는 함수를 실행하겠다는 의미입니다.
  • `events`: 이 함수를 트리거할 이벤트를 정의합니다. 여기서는 `http` 이벤트를 사용하여 API Gateway를 통해 `/hello` 경로로 들어오는 `GET` 요청에 응답하도록 했습니다.

3. `handler.js` 파일 작성

이제 `handler.js` 파일을 열어 `hello` 함수의 코드를 작성합니다. 이 함수는 간단하게 "Hello from Lambda!" 메시지를 반환할 겁니다.

// handler.js
'use strict';

module.exports.hello = async (event) => {
  return {
    statusCode: 200, // HTTP 상태 코드
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(
      {
        message: 'Hello from Lambda!',
        input: event, // Lambda로 전달된 이벤트 객체
      },
      null,
      2
    ),
  };
};

Lambda 함수의 반환 값은 API Gateway 프록시 통합에서 인식할 수 있는 형식을 따라야 합니다. `statusCode`는 HTTP 응답 상태를 나타내고, `body`에는 클라이언트에게 보낼 실제 응답 데이터가 JSON 문자열 형태로 담깁니다. `input: event`를 통해 Lambda 함수가 어떤 요청을 받았는지도 확인할 수 있도록 했습니다.

API 배포 및 관리: 실제 서비스처럼

이제 API가 준비되었으니 AWS에 배포해볼까요? Serverless Framework 덕분에 배포는 매우 간단합니다.

1. 서버리스 API 배포

프로젝트 루트 디렉토리(`my-serverless-api`)에서 다음 명령어를 실행합니다.

sls deploy

이 명령어를 실행하면 Serverless Framework는 다음 작업을 자동으로 수행합니다.

1. `serverless.yml` 파일을 분석하여 필요한 AWS 리소스들을 파악합니다.
2. Lambda 함수 코드를 압축하고, AWS S3 버킷에 업로드합니다.
3. AWS CloudFormation 스택을 생성하거나 업데이트합니다. 이 스택은 Lambda 함수, API Gateway 엔드포인트, IAM 역할 등 필요한 모든 AWS 리소스를 정의하고 프로비저닝합니다.
4. 배포가 완료되면, 터미널에 API Gateway 엔드포인트 URL이 출력됩니다.

배포에는 몇 분 정도 시간이 소요될 수 있습니다. 배포가 성공적으로 완료되면 아래와 비슷한 출력을 볼 수 있습니다.

...
Service "my-serverless-api" deployed to stage "dev" in region "ap-northeast-2"
...
endpoints:
  GET - https://xxxxxxxxx.execute-api.ap-northeast-2.amazonaws.com/dev/hello
functions:
  hello: my-serverless-api-dev-hello
...

`endpoints` 섹션에 있는 URL을 복사하여 웹 브라우저나 `curl` 명령어로 접속해보세요.

curl https://xxxxxxxxx.execute-api.ap-northeast-2.amazonaws.com/dev/hello

그러면 `{"message":"Hello from Lambda!","input":{...}}`와 같은 응답을 받을 수 있을 겁니다. 축하합니다! 여러분의 첫 번째 서버리스 API가 성공적으로 배포되고 동작하는 것을 확인했습니다.

2. API 업데이트 및 로그 확인

함수 코드를 수정하고 싶다면 `handler.js` 파일을 변경한 후 다시 `sls deploy` 명령어를 실행하기만 하면 됩니다. Serverless Framework가 변경된 부분만 감지하여 효율적으로 업데이트를 수행합니다. 예를 들어, 메시지를 "Hello again from Lambda!"로 변경하고 다시 배포해보세요.

함수가 제대로 동작하는지, 혹시 에러는 없는지 확인하고 싶을 때는 로그를 확인하는 것이 중요하죠. Serverless Framework는 AWS CloudWatch Logs에 접근하여 로그를 실시간으로 스트리밍해주는 기능도 제공합니다.

sls logs -f hello -t

`-f hello`는 `hello` 함수에 대한 로그를 보겠다는 의미이고, `-t`는 실시간으로(tail) 로그를 보여주겠다는 의미입니다. API를 호출하면서 이 명령어를 실행하면 함수가 실행될 때마다 출력되는 로그를 터미널에서 바로 확인할 수 있습니다.

3. 배포된 API 제거

이제 테스트를 마쳤으니, 생성된 리소스들을 깔끔하게 제거해야겠죠? AWS 비용이 발생하지 않도록 불필요한 리소스는 제거하는 것이 좋습니다.

sls remove

이 명령어는 `sls deploy`로 생성했던 모든 AWS 리소스(Lambda 함수, API Gateway, S3 버킷, CloudFormation 스택 등)를 삭제합니다. 다시 한 번 확인 메시지가 뜨면 `y`를 입력하여 진행합니다.

Image by athree23 on Pixabay

실전 팁과 고려사항: 더 나은 서버리스를 위해

Serverless Framework로 API를 구축하고 배포하는 방법을 알아보았으니, 이제 실제 서비스를 만들 때 유용한 몇 가지 팁과 고려사항을 살펴볼까요?

1. 환경 변수 활용

데이터베이스 연결 정보, API 키 등 민감하거나 환경에 따라 달라지는 값들은 코드에 직접 하드코딩하는 대신 환경 변수를 사용하는 것이 좋습니다. `serverless.yml` 파일에서 `provider` 섹션 아래에 `environment`를 정의하여 Lambda 함수에 환경 변수를 주입할 수 있습니다.

# serverless.yml
provider:
  # ...
  environment:
    MY_DATABASE_URL: ${env:DATABASE_URL} # 로컬 환경 변수 사용
    API_KEY: some_secret_key_123

functions:
  # ...

위 예시처럼 `DATABASE_URL`과 같은 환경 변수는 `sls deploy` 시 쉘 환경 변수에서 값을 가져오도록 설정할 수 있습니다. 이는 개발, 스테이징, 운영 환경별로 다른 설정을 적용할 때 매우 유용합니다.

2. 콜드 스타트(Cold Start) 이해 및 최적화

콜드 스타트는 Lambda 함수가 오랫동안 호출되지 않아 실행 환경이 종료되었다가, 다시 호출될 때 새롭게 환경을 초기화하는 과정에서 발생하는 지연 시간을 의미합니다. Node.js 런타임이나 복잡한 의존성을 가진 함수일수록 콜드 스타트 시간이 길어질 수 있습니다. 이를 완화하기 위한 몇 가지 방법이 있습니다.

• 메모리 증대: Lambda 함수에 할당된 메모리를 늘리면 CPU 성능도 함께 향상되어 초기화 시간이 단축될 수 있습니다.
• 경량화된 패키지: 불필요한 라이브러리를 제거하고, 의존성 패키지 크기를 최소화하여 배포 패키지 크기를 줄입니다.
• 프로비저닝된 동시성(Provisioned Concurrency): AWS Lambda의 유료 기능으로, 함수 인스턴스를 미리 초기화 상태로 유지하여 콜드 스타트를 완전히 제거할 수 있습니다. 특정 시간 동안 높은 응답성이 필요한 서비스에 유용합니다.
• 워밍업(Warm-up) 플러그인: 주기적으로 함수를 호출하여 콜드 스타트를 방지하는 플러그인을 사용할 수도 있습니다.

3. 로컬 개발 및 테스트

매번 AWS에 배포하면서 테스트하는 것은 비효율적입니다. `serverless-offline`과 같은 플러그인을 사용하면 Serverless Framework 프로젝트를 로컬에서 AWS Lambda 및 API Gateway를 모방하여 실행할 수 있습니다. 이를 통해 개발 속도를 크게 높일 수 있습니다.

npm install --save-dev serverless-offline

설치 후 `serverless.yml`에 플러그인을 추가하고 `sls offline start` 명령어로 로컬에서 서버를 띄울 수 있습니다.

4. 보안 강화

API는 서비스의 문이므로 보안에 각별히 신경 써야 합니다. API Gateway는 기본적으로 인증 및 권한 부여 기능을 제공합니다.

• IAM 권한: Lambda 함수가 다른 AWS 서비스(DynamoDB, S3 등)에 접근해야 한다면, `serverless.yml`의 `provider` 섹션에 `iamRoleStatements`를 추가하여 필요한 최소한의 권한을 부여해야 합니다.
• API 키(API Key): API Gateway에서 API 키를 생성하여 특정 클라이언트만 API에 접근하도록 제한할 수 있습니다.
• 커스텀 인증자(Custom Authorizer): JWT(JSON Web Token)나 OAuth2와 같은 복잡한 인증 로직이 필요할 경우, 별도의 Lambda 함수를 인증자로 사용하여 요청을 처리하기 전에 인증/인가를 수행하도록 설정할 수 있습니다.

마무리하며: 서버리스, 이제 당신의 차례입니다!

이 글을 통해 Serverless Framework를 활용하여 AWS Lambda 기반의 API를 구축하고 배포하는 전반적인 과정을 살펴보았습니다. 서버 관리의 복잡함에서 벗어나 오직 코드에만 집중할 수 있는 서버리스 아키텍처의 매력과, 이를 현실로 만들어주는 Serverless Framework의 강력함을 직접 경험해보셨으리라 생각합니다.

간단한 "Hello, World!" API부터 시작했지만, 이 기본 지식을 바탕으로 데이터베이스 연동, 이미지 처리, 백그라운드 작업 등 다양한 기능을 가진 복잡한 서버리스 애플리케이션을 얼마든지 만들어낼 수 있습니다. 실제로 많은 기업들이 서버리스를 통해 높은 확장성, 비용 효율성, 빠른 개발 주기를 달성하고 있습니다.

이제 여러분의 아이디어를 서버리스로 구현해볼 차례입니다. 처음에는 생소하게 느껴질 수 있지만, 한 단계씩 따라 하다 보면 어느새 서버리스 전문가가 되어 있을 거예요. 혹시 이 글을 읽으면서 궁금했던 점이나, Serverless Framework를 사용하면서 겪었던 재미있는 경험이 있다면 댓글로 자유롭게 공유해주세요! 여러분의 피드백은 더 나은 콘텐츠를 만드는 데 큰 힘이 됩니다. 다음 튜토리얼에서 또 만나요!

📌 함께 읽으면 좋은 글

• [클라우드 인프라] GitOps로 쿠버네티스 애플리케이션 배포 및 관리 자동화: Argo CD 활용 심화 가이드
• [개발 도구] Zsh Oh My Zsh 터미널 최적화 개발 생산성 향상 가이드
• [튜토리얼] Next.js 프로젝트에 TypeScript, ESLint, Prettier 완벽 설정 가이드

이 글이 도움이 되셨다면 공감(♥)과 댓글로 응원해 주세요!
궁금한 점이나 다루었으면 하는 주제가 있다면 댓글로 남겨주세요.