-
Notifications
You must be signed in to change notification settings - Fork 1
ADR 0001 Lambda Version Alias Deployment
SANGMIN PARK edited this page Jul 18, 2026
·
4 revisions
- 상태: Accepted
- 결정일: 2026-03-10
- 마지막 검증: 2026-07-18
전환 안내. 아래의 엄격한 버전 검증, metadata 선보존과 Release 추적 본문 확장 결정은 backend issue #306이
main에 반영된 뒤 효력이 있습니다. 반영 전에는main의 실제 workflow를 기준으로 판단합니다.
Spring Boot API를 AWS Lambda에서 운영하려면 재현 가능한 산출물, 배포 완료 판정, 빠른 코드 롤백 수단이 필요합니다. $LATEST를 직접 트래픽 대상으로 사용하면 어떤 코드가 요청을 처리하는지 확인하기 어렵고 이전 코드로 되돌리는 과정도 불명확합니다.
DB 마이그레이션, Lambda 코드, 런타임 환경 변수와 IAM을 한 워크플로가 모두 관리하면 권한과 실패 범위도 지나치게 커집니다.
- Spring Boot 애플리케이션은 AWS Serverless Java Container의
RequestStreamHandler로 실행합니다. - 배포 산출물은
classes,resources,lib/*.jar를 담은haksa-lambda.zip입니다. - 배포 워크플로는 DB 마이그레이션, 테스트, ZIP 생성, Commit SHA 기반 S3 업로드 순서로 실행합니다. prod migration은 현재 운영 중인 이전 Lambda 코드와 backward compatible해야 합니다.
-
update-function-code --publish로 불변 Version을 생성하고 Active 상태를 확인한 뒤 환경별 Alias를 새 Version으로 전환합니다. - Alias가 새 Version을 가리키는지 확인해야 배포 성공으로 판정합니다.
- dev는 실행한 Git ref를 사용합니다. prod는
main에서만 실행하고 다른 ref는 preflight에서 실패합니다. Workflow dispatch 시점의 commit SHA를 Migration, Lambda build, S3 Object와 릴리즈에 공통으로 사용합니다. - prod는 각 숫자가
0또는 선행 0 없는 양의 정수인 최종MAJOR.MINOR.PATCH형식의 Semantic Version을 입력받습니다. prerelease와 build suffix는 허용하지 않으며, 정식 릴리즈는release/v{버전}에서 확정한 버전을 사용합니다. preflight에서 버전 형식과 기존be-v{버전}태그 중복을 Migration 전에 검증합니다. - Alias 검증이 성공한 뒤 Actions Summary를 작성하고 deployment metadata artifact를 업로드한 다음 배포 commit에
be-v{버전}annotated tag와 GitHub Release를 생성합니다. - GitHub Release 본문에는 제품 버전, commit SHA, Lambda published version과 alias version을 기록하고 자동 생성 릴리즈 노트를 함께 유지합니다.
- 워크플로의 책임은 코드 게시, Alias 전환, 릴리즈 추적 정보 게시까지입니다. Lambda 환경 변수, IAM, Layer, Extension, API Gateway는 외부 인프라에서 관리합니다.
절차는 단순하지만 배포 이력과 트래픽 대상이 불명확하고 Alias 전환을 이용한 즉시 롤백이 어렵습니다.
기존 EC2 워크플로는 비상 롤백 경로로 유지하지만, 현재 기본 배포 경로는 Lambda입니다. 두 런타임을 동시에 주 경로로 관리하면 설정 차이와 검증 비용이 커집니다.
한 번에 배포할 수 있지만 애플리케이션 배포 권한이 IAM과 네트워크 변경까지 확대됩니다. 현재 저장소에는 인프라의 전체 상태도 없으므로 범위에서 제외합니다.
- 제품 버전, commit SHA, S3 Object, Lambda Published Version, Alias를 Summary, metadata artifact와 Release 본문에서 교차 추적할 수 있습니다.
- 코드 문제가 발생하면 Alias를 직전 정상 Version으로 되돌릴 수 있습니다.
- Version이 Active가 되지 않거나 Alias 검증이 실패하면 워크플로가 성공으로 끝나지 않습니다.
- 태그나 Release 게시 전에 Summary와 metadata artifact가 남아 게시 부분 실패를 복구할 근거가 보존됩니다.
- DB 마이그레이션은 Alias 롤백으로 되돌아가지 않습니다. Migration 이후 테스트·빌드·Lambda 게시가 실패해도 이전 Alias가 트래픽을 처리하므로 이전 코드와 새 스키마가 호환돼야 합니다.
- Alias 검증 뒤 태그 또는 GitHub Release 게시가 실패하면 배포는 성공했지만 릴리즈 기록 게시는 실패한 부분 성공 상태로 남습니다.
- 런타임 환경 변수와 IAM 오류는 코드 워크플로만으로 수정하거나 검증할 수 없습니다.
- prod Lambda에
SPRING_PROFILES_ACTIVE=prod가 없으면 코드 기본값인develop-shadow가 선택될 수 있습니다.
- 배포 후 Published Version과 Alias Version이 같은지 확인합니다.
- prod migration은 이전 Lambda 코드와 backward compatible하게 작성합니다. 적용된 migration을 수정하거나 자동 rollback하지 않고, 보정은 다음 version의 forward migration으로 수행합니다.
- Alias 검증 뒤 Summary와 metadata artifact가 생성된 것을 확인한 다음 태그와 Release를 확인합니다.
- 이미 게시한
be-v{버전}태그는 삭제하거나 다른 commit으로 이동하지 않습니다. - 태그 push 후 GitHub Release 생성만 실패하면 Actions run SHA, 역참조한 tag SHA, metadata artifact의 Lambda versions와 live Alias를 대조한 뒤 같은 태그에 GitHub Release만 복구합니다.
- prod 배포 실패 시 마이그레이션 적용 여부와 이전 코드의 스키마 호환성을 먼저 확인합니다.
- Lambda 환경 변수, IAM, Layer 변경을 애플리케이션 배포 완료로 간주하지 않습니다.
- 버전, 태그, GitHub Release와 부분 실패 복구는 Release Management를 따릅니다. 롤백과 장애 대응은 Deployment and Operations와 Troubleshooting을 따릅니다.
- Lambda 콜드 스타트, 실행 시간 또는 패키지 크기가 서비스 목표를 지속해서 충족하지 못합니다.
- 별도 IaC 저장소가 Lambda 코드와 인프라를 하나의 검증 가능한 배포 단위로 관리합니다.
- Alias보다 세밀한 트래픽 분할이나 자동 롤백이 필요합니다.