AWS Lambda를 활용해 서버리스 애플리케이션을 개발할 때 많이 사용되는 도구 중 하나가 Serverless Framework입니다. YAML 기반의 간결한 설정만으로 Lambda 함수, API Gateway, DynamoDB, IAM Role 등 다양한 AWS 리소스를 정의하고 배포할 수 있어 개인 프로젝트부터 상용 서비스까지 폭넓게 활용되고 있습니다.
Serverless Framework는 지속적인 기능 개선과 개발 환경의 변화를 반영하면서 v3에서 v4로 주요 버전이 변경되었습니다. 특히 v4에서는 CLI 인증 정책과 라이선스 체계가 달라졌으며, 기존에 별도 플러그인으로 처리하던 일부 기능이 프레임워크 자체에 통합되었습니다.
기존 v3 프로젝트를 운영하고 있다면 이러한 변경 사항을 정확하게 파악하는 것이 중요합니다. 버전만 변경하면 대부분의 AWS 프로젝트가 기존 설정을 유지한 채 동작하지만, 인증 방식이나 빌드 도구, 플러그인 구성에 따라 추가적인 조정이 필요할 수 있기 때문입니다.
이 글에서는 Serverless Framework v3와 v4의 핵심적인 차이점을 살펴보고, 기존 프로젝트를 안전하게 마이그레이션하는 방법과 배포 과정에서 주의해야 할 사항을 단계별로 설명합니다.
1. Serverless Framework v3와 v4의 주요 변경 사항
Serverless Framework v4는 기존 v3의 사용 방식을 최대한 유지하면서 개발 편의성과 유지보수성을 개선한 버전입니다. AWS 기반 프로젝트의 경우 대부분 기존 설정을 그대로 사용할 수 있지만, CLI 운영 정책과 일부 개발 기능에서는 중요한 차이가 존재합니다.
1-1. 라이선스 정책의 변화
v3와 v4의 가장 중요한 차이점 중 하나는 라이선스 정책입니다.
Serverless Framework v3까지는 오픈소스 기반으로 제공되어 별도의 사용료 없이 자유롭게 활용할 수 있었습니다. 그러나 v4부터는 라이선스 정책이 변경되면서 일정 규모 이상의 기업은 유료 구독이 필요하게 되었습니다.
- v3: MIT 라이선스 기반의 오픈소스 버전으로 제공됩니다.
- v4: 개인 개발자와 소규모 조직은 무료로 사용할 수 있지만, 직전 회계연도 매출이 200만 달러를 초과하는 조직은 유료 구독 라이선스가 필요합니다.
여기서 중요한 점은 Serverless Framework Dashboard의 유료 기능과 CLI 자체의 라이선스 정책은 별개라는 것입니다. Dashboard를 사용하지 않더라도 v4 CLI를 이용할 수 있으며, 라이선스 요건에 해당하지 않는 개발자는 무료로 사용할 수 있습니다.
또한 기존 v3 버전은 2024년 12월 31일 이후 유지보수가 종료되었습니다. 따라서 장기적인 보안 업데이트와 버그 수정을 고려한다면 v4로의 전환을 검토하는 것이 좋습니다.
1-2. CLI 인증 방식 추가
v3에서는 AWS 자격 증명만 정상적으로 설정되어 있다면 별도의 Serverless Framework 계정 인증 없이 배포 명령을 실행할 수 있었습니다.
반면 v4부터는 Serverless Framework CLI 자체에 대한 인증 과정이 추가되었습니다.
인증 방법은 크게 두 가지입니다.
첫 번째는 Serverless Framework Dashboard를 통한 인증입니다.
serverless loginDashboard 계정으로 로그인하면 로컬 환경에 인증 정보가 저장되며, 이후 CLI 명령을 실행할 때마다 반복적으로 로그인할 필요가 없습니다.
CI/CD 환경에서는 Dashboard에서 별도로 생성한 Access Key를 환경 변수로 등록하여 사용할 수 있습니다.
SERVERLESS_ACCESS_KEY=your-access-key두 번째는 License Key를 사용하는 방법입니다.
유료 구독 라이선스를 보유한 조직에서는 License Key를 환경 변수로 전달하여 인증할 수 있습니다.
SERVERLESS_LICENSE_KEY=your-license-keyLicense Key는 Dashboard에 의존하지 않고 CLI 중심으로 운영하려는 조직에 적합합니다.
따라서 로컬 개발 환경과 GitHub Actions, AWS CodeBuild 등의 자동화 환경을 함께 운영하고 있다면 인증 정보를 어떤 방식으로 관리할지 미리 결정하는 것이 좋습니다.
1-3. AWS 이외의 Provider 지원 변경
v3에서는 AWS뿐만 아니라 다른 클라우드 서비스 Provider도 지원했습니다.
그러나 v4에서는 AWS 이외의 기존 Provider 지원이 중단되는 방향으로 정책이 변경되었습니다.
AWS Lambda와 API Gateway를 사용하는 일반적인 프로젝트라면 큰 영향을 받지 않지만, Azure나 Google Cloud 등 다른 Provider를 사용하고 있다면 마이그레이션 전에 대체 도구와 지원 방식을 확인해야 합니다.
특히 여러 클라우드 환경을 하나의 Serverless Framework 프로젝트에서 관리하고 있었다면 이 부분을 우선적으로 검토해야 합니다.
1-4. TypeScript 빌드 기능 내장
v4에서는 JavaScript 및 TypeScript Lambda 함수를 위한 esbuild가 프레임워크 내부에 통합되었습니다.
기존 v3에서는 TypeScript 코드를 JavaScript로 변환하고 배포하기 위해 별도의 빌드 플러그인을 설치하는 경우가 많았습니다.
대표적으로 다음과 같은 플러그인이 사용되었습니다.
- serverless-esbuild
- serverless-webpack
- serverless-plugin-typescript
하지만 v4에서는 별도의 빌드 플러그인 없이도 TypeScript Lambda 함수를 자동으로 빌드할 수 있습니다.
예를 들어 다음과 같은 Handler를 사용할 수 있습니다.
functions:
hello:
handler: src/handlers/hello.main실제 파일이 src/handlers/hello.ts라면 프레임워크가 기본 빌드 기능을 활용하여 배포 가능한 형태로 변환합니다.
추가적인 빌드 설정이 필요한 경우에는 build.esbuild 항목을 사용하면 됩니다.
build:
esbuild:
bundle: true다만 기존 빌드 플러그인을 그대로 유지하면서 v4의 기본 빌드 기능까지 활성화하면 빌드 과정이 중복되거나 충돌할 수 있습니다.
따라서 TypeScript 프로젝트라면 기존 빌드 플러그인의 역할을 확인한 후 기본 빌드 기능으로 전환할지 결정해야 합니다.
Python Lambda 프로젝트에는 이 기능이 직접적인 영향을 주지 않습니다. Python 의존성 설치와 패키징은 기존처럼 별도의 설정이나 플러그인을 통해 관리할 수 있습니다.
1-5. 환경 변수 파일 자동 로딩
v3에서는 .env 파일의 환경 변수를 Serverless 설정에서 사용하려면 일반적으로 useDotenv 옵션을 활성화해야 했습니다.
useDotenv: true하지만 v4에서는 .env와 .env.[stage] 파일을 기본적으로 읽어들입니다.
따라서 기존 설정에서 useDotenv를 제거하더라도 환경 변수가 정상적으로 로딩될 수 있습니다.
다만 여러 환경에서 서로 다른 환경 변수 파일을 사용하거나 별도의 경로에 .env 파일을 관리하고 있다면 실제 로딩 결과를 확인해야 합니다.
특히 개발 환경과 운영 환경의 환경 변수가 혼합되지 않도록 배포 단계에서 검증하는 것이 중요합니다.
1-6. CLI 자동 업데이트 기능
v4에는 프레임워크의 최신 버전을 자동으로 확인하고 업데이트하는 기능이 추가되었습니다.
기본적으로 약 24시간 간격으로 업데이트 여부를 확인하며, 별도의 버전 제한이 없다면 최신 버전으로 업데이트될 수 있습니다.
기존 프로젝트에서 예기치 않은 버전 변경을 방지하려면 serverless.yml에 frameworkVersion을 명시하는 것이 좋습니다.
frameworkVersion: '~4.46.0'위 설정은 4.46.x 범위의 업데이트를 허용하면서 다른 마이너 버전으로 넘어가는 것을 제한합니다.
운영 환경에서는 검증되지 않은 버전이 자동으로 적용되지 않도록 버전 관리 정책을 명확하게 설정하는 것이 좋습니다.
2. v3와 v4의 차이점 한눈에 비교하기
앞서 살펴본 변경 사항을 기준으로 두 버전의 주요 차이를 정리하면 다음과 같습니다.
비교 항목Serverless Framework v3Serverless Framework v4
| 라이선스 | MIT 오픈소스 | 조건부 무료 및 유료 구독 |
| CLI 인증 | 별도 인증 불필요 | Dashboard 또는 License Key |
| AWS Provider | 지원 | 지원 |
| 비 AWS Provider | 지원 | 기존 지원 중단 |
| TypeScript 빌드 | 별도 플러그인 활용 가능 | esbuild 내장 |
| dotenv | 설정을 통한 활성화 | 기본 자동 로딩 |
| 자동 업데이트 | 기본 자동 업데이트 없음 | 24시간 주기 확인 |
| 유지보수 | 종료 | 지속적인 업데이트 |
| stages 설정 | 기존 params 구조 | 새로운 stages 구조 권장 |
두 버전의 핵심적인 차이는 기존 프로젝트의 배포 설정 자체보다는 개발 도구의 운영 방식과 내부 빌드 시스템에 있습니다.
AWS 기반의 Python 프로젝트라면 TypeScript 빌드 기능과 관련된 변경 사항은 크게 신경 쓰지 않아도 됩니다. 반면 인증 방식, CLI 버전 관리, 플러그인 호환성은 언어와 관계없이 확인해야 합니다.
3. 기존 Serverless Framework v3 프로젝트를 v4로 마이그레이션하기
기존 v3 프로젝트를 v4로 변경할 때는 모든 설정을 새롭게 작성할 필요가 없습니다.
Serverless Framework 공식 마이그레이션 가이드에서도 기존 AWS 프로젝트는 대부분 별도의 설정 변경 없이 v4에서 사용할 수 있다고 안내하고 있습니다.
다만 실제 서비스에 적용하기 전에는 개발 환경에서 먼저 검증하는 것이 안전합니다.
3-1. 기존 프로젝트의 설정과 의존성 확인
가장 먼저 현재 프로젝트가 어떤 버전의 Serverless Framework를 사용하고 있는지 확인합니다.
serverless --version다음으로 프로젝트의 package.json과 serverless.yml을 확인합니다.
특히 다음 항목을 점검하는 것이 좋습니다.
- Serverless Framework 버전
- 설치된 Serverless 플러그인 목록
- TypeScript 및 JavaScript 빌드 방식
- Python 의존성 패키징 설정
- AWS Provider 및 Runtime 설정
- 환경 변수 로딩 방식
- Stage별 배포 설정
플러그인을 여러 개 사용하고 있다면 각 플러그인이 v4를 지원하는지도 확인해야 합니다.
기존 프로젝트에서 사용하던 플러그인이 v4에서도 정상적으로 동작하는지는 개별적으로 검증해야 합니다.
3-2. Serverless Framework v4 설치
기존에 전역으로 설치한 v3를 사용하고 있다면 npm을 통해 v4를 설치할 수 있습니다.
npm install -g serverless설치가 완료되면 버전을 다시 확인합니다.
serverless --version프로젝트에서 로컬 의존성으로 Serverless Framework를 관리하고 있다면 package.json의 버전도 함께 확인해야 합니다.
npm install --save-dev serverless@^4전역 버전과 프로젝트 로컬 버전이 서로 다르면 실행 환경에 따라 예상하지 못한 버전이 사용될 수 있으므로, 프로젝트에서 실제로 참조하는 CLI 버전을 확인하는 것이 중요합니다.
3-3. CLI 인증 설정
v4에서는 인증이 필요하므로 로컬 개발 환경에서 먼저 로그인해야 합니다.
serverless login로그인 과정이 완료되면 기존 프로젝트의 배포 명령을 실행할 수 있습니다.
AWS 인증 정보는 Serverless Framework 인증과 별개로 관리됩니다.
즉, 다음 두 가지가 모두 준비되어 있어야 합니다.
- Serverless Framework CLI 인증 정보
- AWS 계정에 접근하기 위한 IAM 자격 증명 또는 AWS Profile
기존에 AWS CLI Profile을 사용하고 있었다면 해당 설정은 그대로 활용할 수 있습니다.
serverless deploy --aws-profile my-profileAWS Profile을 지정하는 방법은 프로젝트의 인증 정책에 따라 달라질 수 있지만, 핵심은 Framework 인증과 AWS 인증을 별개의 절차로 이해하는 것입니다.
3-4. serverless.yml 설정 검토
기존 serverless.yml을 그대로 사용할 수 있는지 확인하고, v4에서 변경된 설정을 점검합니다.
특히 Stage별 파라미터 설정은 새로운 구조를 사용하는 것이 좋습니다.
기존 v3 방식은 다음과 같습니다.
params:
default:
tableName: dev-table
prod:
tableName: production-tablev4에서는 다음과 같은 구조를 권장합니다.
stages:
default:
params:
tableName: dev-table
prod:
params:
tableName: production-table이 변경은 반드시 수행해야 하는 강제 마이그레이션 항목이라기보다는 v4에서 권장하는 설정 구조입니다.
기존 params 구조를 사용하고 있더라도 바로 문제가 발생하는 것은 아니지만, 새로운 설정 방식으로 정리하면 향후 프로젝트 관리에 도움이 됩니다.
3-5. 기존 플러그인 호환성 확인
v4 마이그레이션에서 가장 주의해야 할 부분 중 하나는 플러그인입니다.
기존 v3에서 정상적으로 동작하던 플러그인이 v4에서도 동일하게 동작한다고 보장할 수는 없습니다.
특히 빌드 기능과 관련된 플러그인은 주의해야 합니다.
예를 들어 TypeScript 프로젝트에서 serverless-esbuild를 사용하고 있었다면 v4의 기본 esbuild 기능과 역할이 중복될 수 있습니다.
이 경우 다음 두 가지 방향을 고려할 수 있습니다.
- 기존 빌드 플러그인을 제거하고 v4 내장 기능으로 전환합니다.
- 기존 빌드 방식을 유지하고 v4의 기본 빌드 기능을 비활성화합니다.
반면 Python 프로젝트에서 사용하는 serverless-python-requirements와 같은 플러그인은 TypeScript 빌드 기능과 별개의 역할을 수행하므로, 단순히 v4로 변경했다는 이유만으로 제거할 필요는 없습니다.
중요한 것은 플러그인의 역할과 v4 호환성을 각각 확인하는 것입니다.
3-6. 테스트 Stage에서 배포 검증
모든 설정을 변경했다면 곧바로 운영 환경에 배포하지 말고 별도의 테스트 Stage를 사용하는 것이 좋습니다.
serverless deploy --stage testv4테스트 Stage에 배포하면 기존 운영 환경을 유지하면서 v4의 배포 결과를 검증할 수 있습니다.
배포가 완료되었다면 다음 항목을 확인합니다.
- Lambda 함수가 정상적으로 생성되었는지
- IAM Role과 Policy가 기존과 동일하게 적용되었는지
- API Gateway 및 Event 설정이 정상적으로 생성되었는지
- Lambda Layer가 정상적으로 연결되었는지
- 환경 변수가 올바르게 전달되었는지
- CloudFormation Stack에 예상하지 못한 변경이 발생하지 않았는지
- 실제 Lambda 실행과 로그 출력이 정상적인지
특히 기존 서비스에서 DynamoDB, SQS, EventBridge 등 여러 AWS 리소스를 사용하고 있다면 각 리소스의 생성 및 연결 상태도 확인해야 합니다.
단순히 serverless deploy가 성공했다는 이유만으로 마이그레이션이 완료되었다고 판단해서는 안 됩니다.
4. GitHub Actions 등 CI/CD 환경에서 주의할 사항
로컬 환경에서는 serverless login을 통해 간단하게 인증할 수 있지만, CI/CD 환경에서는 인증 정보를 안전하게 전달할 수 있도록 별도의 설정이 필요합니다.
GitHub Actions를 사용한다면 Repository Secrets 또는 Environment Secrets에 Access Key를 등록할 수 있습니다.
예를 들어 다음과 같이 환경 변수를 전달할 수 있습니다.
- name: Deploy Serverless Application
env:
SERVERLESS_ACCESS_KEY: ${{ secrets.SERVERLESS_ACCESS_KEY }}
run: npx serverless deploy --stage prod여기서 SERVERLESS_ACCESS_KEY는 Serverless Framework Dashboard에서 발급한 Access Key를 의미합니다.
AWS 인증 역시 별도로 설정해야 합니다. 가능하다면 장기적인 IAM Access Key보다는 GitHub Actions OIDC와 AWS IAM Role을 연동하는 방식이 보안 측면에서 유리합니다.
이렇게 구성하면 GitHub Actions가 필요한 권한을 가진 AWS Role을 임시로 획득하여 배포할 수 있습니다.
또한 자동 배포 환경에서는 CLI 버전이 예기치 않게 변경되지 않도록 package.json과 Lock File을 활용하여 버전을 관리하는 것이 좋습니다.
5. v4 마이그레이션 과정에서 자주 발생하는 문제
버전 변경 자체는 간단하지만 기존 프로젝트의 구성에 따라 여러 문제가 발생할 수 있습니다.
대표적인 문제와 해결 방향을 살펴보겠습니다.
5-1. Serverless Framework 인증 오류
v4로 변경한 이후 배포 명령을 실행했을 때 인증 관련 오류가 발생한다면 CLI 인증 정보가 정상적으로 설정되어 있는지 확인해야 합니다.
로컬 환경에서는 다음 명령으로 로그인할 수 있습니다.
serverless loginCI/CD 환경에서는 Dashboard Access Key 또는 적절한 License Key를 설정해야 합니다.
AWS Profile이 정상적으로 설정되어 있더라도 Framework 자체의 인증이 완료되지 않았다면 명령 실행에 문제가 발생할 수 있습니다.
5-2. 빌드 플러그인 충돌
TypeScript 프로젝트에서 기존 빌드 플러그인을 유지한 채 v4의 내장 빌드 기능을 사용하면 빌드 과정이 중복될 수 있습니다.
이 경우 기존 플러그인의 설정을 확인하고 기본 빌드 기능을 비활성화하거나 불필요한 플러그인을 제거해야 합니다.
반대로 Python 프로젝트라면 esbuild가 Python 패키지를 빌드하는 도구가 아니라는 점을 기억해야 합니다.
Python 의존성은 기존 패키징 방식을 유지하면서 별도로 검증해야 합니다.
5-3. 환경 변수 로딩 결과 변경
v4에서는 .env 파일을 기본적으로 읽기 때문에 기존 프로젝트에서 환경 변수 로딩을 직접 제어하고 있었다면 예상과 다른 결과가 발생할 수 있습니다.
특히 .env, .env.dev, .env.prod 등을 함께 사용하는 경우에는 Stage별로 어떤 파일이 적용되는지 확인해야 합니다.
운영 환경의 비밀 정보가 개발 환경에 노출되지 않도록 환경 변수의 우선순위와 관리 방식을 점검하는 것이 좋습니다.
5-4. 자동 업데이트로 인한 배포 환경 차이
개발 환경과 CI/CD 환경에서 서로 다른 Serverless Framework 버전이 사용되면 배포 결과에 차이가 발생할 수 있습니다.
이를 방지하려면 frameworkVersion을 명시하고, CI/CD에서는 Lock File을 기준으로 의존성을 설치하는 것이 좋습니다.
예를 들어 다음과 같이 설정할 수 있습니다.
frameworkVersion: '~4.46.0'버전 범위를 명시적으로 관리하면 예기치 않은 메이저 또는 마이너 업데이트를 방지하는 데 도움이 됩니다.
6. 마이그레이션 이후 안정적인 운영을 위한 권장 사항
Serverless Framework v4로 전환했다면 단순히 배포가 성공했는지만 확인하는 것이 아니라 장기적인 운영 환경까지 고려해야 합니다.
6-1. Framework 버전 고정
운영 환경에서는 검증된 Framework 버전을 기준으로 배포하는 것이 좋습니다.
특히 여러 개발자가 동일한 프로젝트를 관리한다면 개인별 CLI 버전 차이로 인한 문제를 방지해야 합니다.
프로젝트의 frameworkVersion과 패키지 의존성을 함께 관리하면 일관된 배포 환경을 유지할 수 있습니다.
6-2. AWS 권한 최소화
v3에서 사용하던 IAM Policy를 그대로 유지하더라도 마이그레이션 이후 권한 구성을 다시 검토하는 것이 좋습니다.
Lambda 함수가 실제로 사용하는 AWS API만 허용하도록 권한을 최소화하면 불필요한 접근을 방지할 수 있습니다.
특히 운영 환경에서는 관리자 수준의 권한을 배포용 자격 증명에 부여하지 않도록 주의해야 합니다.
6-3. 배포 전후 CloudFormation 변경 사항 확인
Serverless Framework는 AWS CloudFormation을 기반으로 인프라를 관리합니다.
따라서 Framework 버전 변경 이후에는 기존 CloudFormation Stack에 어떤 변경 사항이 발생하는지 확인하는 과정이 필요합니다.
다음 명령을 활용하면 실제 배포 전에 변경 사항을 검토할 수 있습니다.
serverless package --stage prod패키징 결과물과 CloudFormation 템플릿을 기존 배포 결과와 비교하면 예상하지 못한 리소스 변경을 사전에 발견하는 데 도움이 됩니다.
6-4. 실제 Lambda 실행 테스트
마지막으로 배포가 끝난 뒤에는 실제 Lambda 함수의 실행 결과를 검증해야 합니다.
API Gateway 요청, EventBridge 스케줄, DynamoDB 연동, 외부 API 호출 등 프로젝트에서 사용하는 핵심 기능을 직접 테스트하는 것이 좋습니다.
특히 Lambda Layer와 외부 Python 패키지를 사용하는 프로젝트라면 패키지 경로와 Import 오류가 발생하지 않는지도 확인해야 합니다.
배포 성공과 실제 애플리케이션 정상 동작은 서로 다른 문제이므로 반드시 구분해서 검증해야 합니다.
7. 기존 v3 프로젝트라면 v4로 전환하는 것이 좋을까?
기존 v3 프로젝트를 운영하고 있다면 v4로의 전환을 적극적으로 검토하는 것이 좋습니다.
v3는 2024년 12월 31일 이후 유지보수가 종료되었기 때문에 장기적으로 보안 업데이트와 버그 수정에 대한 기대가 어렵습니다.
반면 v4는 기존 AWS 프로젝트와의 호환성을 최대한 유지하면서 지속적으로 기능이 추가되고 있습니다.
다만 모든 프로젝트가 즉시 전환해야 하는 것은 아닙니다. 특히 복잡한 플러그인 구성이나 자체적으로 작성한 커스텀 플러그인을 사용하고 있다면 충분한 테스트 기간을 확보해야 합니다.
프로젝트 유형에 따라 다음과 같이 판단할 수 있습니다.
프로젝트 유형권장 방향
| AWS Lambda 기반 Python 프로젝트 | v4 전환 권장 |
| AWS Lambda 기반 Node.js 프로젝트 | 빌드 플러그인 검토 후 전환 |
| TypeScript 기반 프로젝트 | 내장 esbuild 활용 검토 |
| 다수의 커스텀 플러그인 사용 | 호환성 검증 후 전환 |
| AWS 이외의 Provider 사용 | 대체 도구 검토 필요 |
결론적으로 Serverless Framework v4는 기존 v3 프로젝트의 구조를 크게 변경하지 않으면서도 개발 환경과 유지보수 측면에서 개선된 버전입니다.
특히 AWS Lambda를 중심으로 서비스를 운영하고 있다면 인증 정책과 플러그인 호환성, 배포 결과만 충분히 검증한 뒤 점진적으로 전환하는 방법을 추천합니다.
기존 설정을 무작정 변경하기보다는 테스트 Stage에서 먼저 배포하고, 실제 AWS 리소스와 Lambda 실행 결과를 확인한 후 운영 환경에 적용하는 것이 안전합니다.
안정적인 서버리스 운영을 위해서는 단순한 버전 업그레이드보다 재현 가능한 빌드 환경과 검증된 배포 절차를 함께 구축하는 것이 중요합니다.