로컬에서 잘 돌아가던 앱이 클라우드에만 올리면 왜 망가질까? 2011년 Heroku 엔지니어들이 수천 개의 앱 배포 경험에서 뽑아낸 12가지 원칙을 한국어로, 비유와 안티패턴 중심으로 풀어본다. Docker, Kubernetes, 서버리스 시대에도 여전히 유효한 클라우드 네이티브 앱의 기본기.
내 노트북에서는 완벽하게 돌아간다. 테스트도 통과하고, API도 잘 응답한다. 그런데 AWS에 올리면 환경변수 에러, 파일 업로드 소실, 로그 실종. 이것은 능력의 문제가 아니라 설계 원칙의 문제다.
2011년, Heroku의 엔지니어들이 수천 개의 앱 배포 경험에서 깨달았다. 클라우드에서 잘 돌아가는 앱에는 공통된 패턴이 있고, 망가지는 앱에도 공통된 안티패턴이 있다. 그것을 12가지 원칙으로 정리한 것이 12-Factor App이다.
이 글에서는 12가지 원칙을 한국어 비유, 안티패턴, 코드 예시와 함께 풀어본다.
저자는 Adam Wiggins — Heroku 공동 창립자이자, 수천 개의 SaaS 앱 배포를 직접 지켜본 엔지니어다.
2010년대 초반 — 온프레미스에서 클라우드로, 모놀리식에서 마이크로서비스로 전환되는 과도기. Wiggins와 동료들은 반복되는 실패 패턴을 발견했다.
12-Factor가 해결하려는 핵심 문제 세 가지: (1) 환경 간 차이 최소화, (2) 이식성 — 어디서든 실행, (3) 확장성 — 수평 확장이 자연스러운 구조.
하나의 코드베이스, 여러 번의 배포
원칙: 앱은 하나의 Git 저장소에서 관리. 여러 환경에 배포되지만, 코드는 동일한 저장소에서 나온다.
안티패턴: 환경별로 코드 브랜치를 따로 관리(main-dev, main-prod), 하나의 앱을 여러 저장소에 복사-붙여넣기로 동기화, 서로 다른 앱을 한 저장소에 합침.
명시적으로 선언하고, 격리한다
원칙: 모든 라이브러리/도구는 명시적 선언 파일에 기록. 시스템 전역 패키지에 의존하면 안 된다.
안티패턴: sudo apt-get install imagemagick으로 서버에 직접 설치하고, 코드에서는 "깔려 있겠지" 가정. 새 서버 배포 시마다 반복되는 "아, 설치 안 했네" 문제.
올바른 방법:
# Dockerfile로 시스템 의존성까지 명시
FROM python:3.12-slim
RUN apt-get update && apt-get install -y libmagickwand-dev
COPY requirements.txt .
RUN pip install -r requirements.txt
설정은 환경변수에 저장한다
원칙: DB 접속 정보, API 키, 외부 서비스 URL 등은 코드 밖, 환경변수(environment variable)에 저장한다.
안티패턴 vs 올바른 방법:
DB_HOST = "192.168.1.100" 하드코딩 → os.environ["DB_HOST"] 환경변수에서 읽기config/production.yml 환경별 파일 → DATABASE_URL 환경변수 하나로 통일.env는 .gitignore에 등록, 프로덕션에서는 시크릿 매니저if env == "prod" 코드 분기 → 환경변수 값만 바꾸면 동작이 달라지도록 설계리트머스 테스트: 지금 이 순간, 코드를 오픈소스로 공개해도 보안 문제가 없는가? "아니요"라면 코드에 비밀이 하드코딩되어 있다.
백엔드 서비스를 연결된 리소스로 취급한다
원칙: DB, 메시지 큐, 캐시, SMTP 등 모든 외부 서비스는 연결된 리소스(attached resource)로 취급한다. URL만 바꾸면 다른 서비스로 교체할 수 있어야 한다.
안티패턴: db = mysql.connector.connect(host="localhost", user="root", password="1234") — 환경이 바뀌면 코드를 수정해야 한다.
올바른 방법: engine = create_engine(os.environ["DATABASE_URL"]) — URL만 바꾸면 로컬 MySQL에서 AWS RDS로 즉시 전환 가능. 프로덕션 DB 장애 시 코드 변경 없이 백업 DB로 전환할 수 있다면 이 원칙을 잘 따르고 있다.
빌드 단계와 실행 단계를 엄격히 분리한다
npm run build, docker build
v2.3.1-20260401)
안티패턴: 프로덕션 서버에 SSH로 접속해서 vi app.py로 코드를 직접 수정 (Run 단계에서 Build를 하는 꼴). 배포할 때마다 서버에서 npm install 실행. 릴리스에 고유 버전이 없어서 롤백 불가.
앱을 하나 이상의 무상태(stateless) 프로세스로 실행한다
원칙: 각 프로세스는 무상태(stateless). 영구 데이터는 DB나 캐시 같은 외부 서비스에 저장한다.
안티패턴: 세션을 서버 메모리에 저장 — 두 번째 서버로 요청이 가면 장바구니가 비어 있다.
올바른 방법: Redis에 세션 저장 — 어떤 서버가 처리해도 같은 결과. 이 원칙은 수평 확장의 전제 조건이다.
포트 바인딩을 통해 서비스를 공개한다
원칙: Apache/Tomcat에 앱을 주입하는 방식이 아니라, 앱 자체가 HTTP 포트를 열고 서비스를 제공한다.
// Express.js — 앱 자체가 HTTP 서버
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Listening on port ${PORT}`));
이 원칙 덕분에 앱이 다른 앱의 백엔드 서비스가 될 수 있다. 마이크로서비스 아키텍처의 기반 개념이다.
프로세스 모델을 통해 확장한다
원칙: 서버 사양을 올리는 것(수직 확장)이 아니라 프로세스 수를 늘린다(수평 확장). 작업 유형별로 분류하고 독립 확장한다.
# Kubernetes — 프로세스 유형별 독립 스케일링
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
spec:
replicas: 4 # 트래픽에 따라 조절
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: worker
spec:
replicas: 2 # 큐 크기에 따라 조절
안티패턴: 하나의 프로세스에서 웹 요청 + 백그라운드 작업 + 스케줄러를 모두 처리. "CPU를 128코어로 올리자"는 수직 확장의 한계에 도달.
빠른 시작과 우아한 종료로 견고성을 극대화한다
원칙: 프로세스는 빠르게 시작, 우아하게 종료. 언제든 새 인스턴스를 띄우거나 내릴 수 있어야 한다.
// Node.js graceful shutdown
process.on('SIGTERM', async () => {
server.close(); // 1. 새 요청 받지 않기
await flushQueue(); // 2. 진행 중 작업 완료
await db.end(); // 3. DB 연결 종료
process.exit(0);
});
쿠버네티스는 스케일링, 업데이트, 장애 복구 시 프로세스를 수시로 종료하고 시작한다. 시작은 수 초 이내, 종료는 진행 중 작업 완료 보장이 목표다.
개발, 스테이징, 프로덕션 환경을 최대한 비슷하게 유지한다
원칙: 세 가지 간극을 최소화한다. 시간 간극(수 주 뒤 배포 → 수 시간 내 배포), 인적 간극(개발자/운영 분리 → 개발자가 직접 배포), 도구 간극(dev SQLite/prod PostgreSQL → 모든 환경에서 동일 도구).
특히 도구 간극이 위험하다. Docker Compose면 로컬에서도 프로덕션과 동일한 DB, 캐시, 큐를 띄울 수 있다.
로그를 이벤트 스트림으로 취급한다
원칙: 로그는 그냥 stdout(표준 출력)으로 내보내면 된다. 저장, 라우팅, 보관은 실행 환경이 처리한다.
안티패턴: logging.FileHandler('/var/log/myapp/app.log') — 컨테이너가 죽으면 로그도 사라진다.
올바른 방법: logging.basicConfig(stream=sys.stdout) — 컨테이너(Docker, K8s)는 stdout을 자동 수집하고, 개발 중에는 터미널에서 바로 볼 수 있다.
관리/유지보수 작업을 일회성 프로세스로 실행한다
원칙: DB 마이그레이션, 일회성 스크립트 등 관리 작업은 앱과 동일한 환경, 동일한 코드베이스와 설정으로 실행한다.
# 앱과 동일한 환경에서 관리 명령 실행
kubectl exec -it deploy/myapp -- python manage.py migrate # K8s
heroku run python manage.py createsuperuser # Heroku
안티패턴: 프로덕션 DB에 직접 접속해서 SQL 수동 실행. 관리 스크립트를 별도 저장소에서 관리(코드베이스 불일치).
현실의 고통 세 가지를 12-Factor로 해결해 보자.
kubectl rollout undo 한 줄이면 30초 내 복구.이후 등장한 기술들은 12-Factor를 더 쉽게 따를 수 있게 만들어주었다.
Docker는 12-Factor의 최고 파트너다. Dockerfile이 의존성을 명시하고(II), docker build/docker run이 Build/Release/Run을 자연스럽게 분리하며(V), 동일한 이미지로 Dev/Prod Parity를 보장하고(X), stdout을 자동 수집한다(XI).
Kubernetes는 12-Factor의 실행 플랫폼이다. ConfigMap/Secret으로 설정을 주입하고(III), HPA로 자동 수평 확장하며(VIII), Rolling update로 무중단 배포하고(IX), Job/CronJob으로 관리 작업을 자동화한다(XII).
서버리스(AWS Lambda, Vercel Functions)는 12-Factor를 강제한다.
12-Factor를 이해하면 서버리스가 왜 그렇게 설계되었는지 자연스럽게 이해된다.
12가지 원칙은 여전히 유효하지만, 15년이 지나며 몇 가지 추가 고려사항이 생겼다.
2016년, Pivotal의 Kevin Hoffman은 3가지 원칙을 추가했다: XIII. API First (설계 단계부터 API 계약 정의), XIV. Telemetry (로그뿐 아니라 메트릭+트레이싱 수집), XV. Auth/Security (제로 트러스트 환경에서 인증을 앱 설계에 포함).
2011년에는 Docker(2013)도, 서버리스도 없었다. 2026년에는 Docker+K8s가 표준, OpenTelemetry로 관찰가능성 통합, ArgoCD로 GitOps, Terraform으로 IaC까지 갖추었다.
각 항목에 "예/아니오"로 답해 보자.
npm install 한 줄로 환경 구성 완료처음부터 다 지키려 하지 말자. Factor III(Config), Factor VI(Processes), Factor X(Dev/Prod Parity)가 가장 즉각적인 효과를 준다.
"마이크로서비스 전용?" — 아니다. 모놀리식에도 적용된다. 마이크로서비스 전환 전에 먼저 적용하는 것이 올바른 순서.
"다 지켜야?" — 가이드라인이지 법칙이 아니다. Factor III(Config)과 II(Dependencies)는 어떤 프로젝트든 지키는 게 좋다.
"성능 저하?" — 오히려 수평 확장이 쉬워진다. Redis 세션 저장의 네트워크 왕복은 체감 불가 수준.
"2011년이라 구식?" — HTTP가 1991년에 나왔다고 구식이라 하지 않듯, 원칙은 시대를 초월한다.
한 문장으로 요약하면 이렇다:
코드와 설정을 분리하고, 상태를 외부에 저장하고, 모든 것을 자동화하라.
이것만 기억해도 "로컬에서는 되는데 클라우드에서는 안 되는" 문제의 80%는 예방할 수 있다.
체크리스트에서 가장 점수가 낮은 항목 하나부터 개선하자. 그것이 클라우드 네이티브로 가는 첫걸음이다.
더 읽어볼 자료: