Twelve-Factor App methodology

Twelve-Factor App Methodology

Twelve-Factor App Methodology 는 Heroku 의 개발자들이 2011 년에 제안한 클라우드 기반 애플리케이션 개발을 위한 12 가지 원칙이다.
이 방법론은 언어, 프레임워크, 플랫폼에 독립적으로 적용 가능하며, 코드베이스 관리, 종속성 선언, 구성 설정, 백엔드 서비스 처리, 빌드 및 릴리스 관리, 프로세스 실행, 포트 바인딩, 동시성 처리, 폐기성, 개발/운영 환경 일치, 로그 처리, 관리 프로세스 실행 등 다양한 측면을 다루며, 애플리케이션의 이식성, 확장성, 유지보수성을 향상시키는 데 중점을 둔다.

핵심 개념

Twelve-Factor App은 SaaS(Software as a Service) 및 클라우드 네이티브 환경에 최적화된 애플리케이션 개발을 위한 12 가지 실천 원칙을 의미한다. 이 방법론은 언어, 프레임워크, 플랫폼에 독립적이며, 소프트웨어의 이식성, 확장성, 유지보수성, 자동화된 배포를 목표로 한다.
Twelve-Factor App Methodology 는 다음과 같은 12 가지 원칙으로 구성된다:

1. 코드베이스 (Codebase): 하나의 코드베이스를 유지하며, 여러 배포 환경에서 사용한다.
2. 종속성 (Dependencies): 모든 종속성을 명시적으로 선언하고 격리한다.
3. 구성 (Config): 구성은 환경 변수에 저장하여 코드와 분리한다.
4. 백엔드 서비스 (Backing Services): 데이터베이스나 메시지 큐와 같은 백엔드 서비스를 연결된 리소스로 취급한다.
5. 빌드, 릴리스, 실행 (Build, Release, Run): 빌드, 릴리스, 실행 단계를 명확히 분리한다.
6. 프로세스 (Processes): 애플리케이션을 하나 이상의 무상태 프로세스로 실행한다.
7. 포트 바인딩 (Port Binding): 서비스를 포트에 바인딩하여 외부에 노출한다.
8. 동시성 (Concurrency): 프로세스를 복제하여 확장성을 확보한다.
9. 폐기성 (Disposability): 빠른 시작과 종료를 통해 탄력성을 높인다.
10. 개발/운영 환경 일치 (Dev/Prod Parity): 개발, 스테이징, 운영 환경의 차이를 최소화한다.
11. 로그 (Logs): 애플리케이션은 로그를 이벤트 스트림으로 처리한다.
12. 관리 프로세스 (Admin Processes): 관리 작업은 일회성 프로세스로 실행한다.

목적 및 필요성

이 방법론의 주요 목적은 다음과 같다:

• 자동화 설정: 선언적 형식 사용으로 새로운 개발자의 시간과 비용 최소화
• 이식성: 실행 환경 간 최대 이식성 제공
• 클라우드 배포: 현대적인 클라우드 플랫폼에 적합한 배포
• 지속적 배포: 개발과 프로덕션 간의 차이 최소화로 최대 민첩성 확보
• 확장성: 툴링, 아키텍처, 개발 관행의 중대한 변경 없이 확장 가능

주요 기능 및 역할

12-Factor 방법론을 사용하는 개발자가 구축한 애플리케이션은 앱이 확장될 때 다양한 시나리오를 다루는 공통적인 특성을 갖게 된다.

주요 기능은 다음과 같다:

• 환경 독립성: 운영체제와의 깔끔한 계약으로 최대 이식성 제공
• 자동화 지원: 설정 자동화를 위한 선언적 형식 사용
• 수평적 확장: 중요한 재작업 없이 쉬운 확장
• 언어 중립성: 모든 프로그래밍 언어와 백엔드 서비스 조합에 적용 가능

특징

12-Factor App 의 주요 특징은 다음과 같다:

• 클라우드 네이티브 설계: 컨테이너화된 클라우드 환경에 최적화
• 마이크로서비스 친화적: 개별 서비스의 독립적 개발과 배포 지원
• 무상태 프로세스: 세션이나 워크플로우 상태를 프로세스에 저장하지 않음
• 환경 분리: 코드와 설정의 명확한 분리
• 백업 서비스 추상화: 로컬과 원격 서비스를 동일하게 취급

핵심 원칙

각 항목은 Docker, Kubernetes, AWS 등의 운영 환경에 따라 구체적으로 달라질 수 있으며, 상황에 맞는 확장도 가능하다.

Codebase (코드베이스)

원칙: 하나의 애플리케이션은 하나의 코드베이스를 갖는다.
설명: 모든 배포 환경 (개발, 스테이징, 프로덕션 등) 에서 동일한 코드베이스를 사용하며, 버전 관리 시스템 (Git 등) 으로 관리된다. 단일 앱은 단일 코드베이스와 1:1 관계를 가져야 하며, 여러 앱이 하나의 코드베이스를 공유하거나, 하나의 앱이 여러 코드베이스를 사용하는 것은 지양한다. 마이크로서비스 아키텍처에서는 서비스별로 각각의 코드베이스를 둘 수 있다
특징:

• 단일 코드 저장소 (Repository) 사용

• 버전 관리 시스템 (Git, SVN 등) 활용

• 환경별 설정만 분리, 코드베이스는 동일

• 코드베이스와 앱의 1:1 관계 유지
  실전 예시:

• 단일 서비스 구조

  1 2 3 4 5 6 7 8 9 10 11 12 13

  my-web-app/ ├── .git/ ├── src/ │ ├── controllers/ │ ├── models/ │ └── views/ ├── config/ │ ├── development.json │ ├── staging.json │ └── production.json ├── package.json ├── Dockerfile └── README.md

• 마이크로서비스 구조 (Multi-repo 방식)

  1 2 3 4 5 6 7 8 9 10 11 12

  # 각 서비스별 독립된 리포지토리 user-service/ ├── .git/ ├── src/ ├── Dockerfile └── package.json order-service/ ├── .git/ ├── src/ ├── Dockerfile └── package.json

• 마이크로서비스 구조 (Mono-repo 방식)

  1 2 3 4 5 6 7 8 9 10 11 12 13

  e-commerce-platform/ ├── .git/ ├── services/ │ ├── user-service/ │ │ ├── src/ │ │ └── Dockerfile │ ├── order-service/ │ │ ├── src/ │ │ └── Dockerfile │ └── payment-service/ ├── shared/ │ └── libraries/ └── docker-compose.yml

Dependencies (의존성)

원칙: 모든 의존성을 명시적으로 선언하고 격리한다.
설명: 애플리케이션이 필요로 하는 모든 라이브러리, 패키지, 모듈 등 의존성을 명확히 선언하고, 시스템에 암묵적으로 존재하는 패키지에 의존하지 않는다. 의존성 관리 도구와 격리 환경 (가상환경, 컨테이너 등) 을 활용해 환경 간 일관성을 보장한다
특징:

• 의존성 선언 (manifest) 파일 사용 (예: package.json, requirements.txt)

• 종속성 관리 도구 사용 (npm, pip, Maven, Gradle 등)

• 시스템 전역 패키지에 의존하지 않음

• 가상환경, Docker 등으로 환경 격리
  실전 예시:

• Node.js 프로젝트

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

  { "name": "my-app", "version": "1.0.0", "dependencies": { "express": "^4.18.2", "mongoose": "^7.5.0", "jsonwebtoken": "^9.0.2", "bcryptjs": "^2.4.3" }, "devDependencies": { "nodemon": "^3.0.1", "jest": "^29.6.4" }, "engines": { "node": ">=18.0.0" } }

• Python 프로젝트

  1 2 3 4 5 6 7 8 9 10 11

  # requirements.txt Flask==2.3.3 SQLAlchemy==2.0.21 requests==2.31.0 gunicorn==21.2.0 python-dotenv==1.0.0 # requirements-dev.txt pytest==7.4.2 black==23.9.1 flake8==6.1.0

• Docker 를 통한 종속성 격리

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

  FROM node:18-alpine WORKDIR /app # 종속성 파일만 먼저 복사 (캐시 효율성) COPY package*.json ./ # 종속성 설치 (정확한 버전으로) RUN npm ci --only=production # 애플리케이션 코드 복사 COPY . . # 비root 사용자로 실행 (보안) USER node EXPOSE 3000 CMD ["npm", "start"]

Config (설정)

원칙: 환경설정을 코드와 분리하여 관리한다.
설명: 환경별로 달라지는 설정 (데이터베이스 URL, API 키, 비밀 정보 등) 은 코드에 포함하지 않고 환경변수, 보안 저장소 (Kubernetes Secret, Vault 등) 로 관리한다. 이를 통해 코드 변경 없이 환경에 따라 설정만 바꿔 배포할 수 있다.
특징:

• 환경변수로 설정값 관리

• 민감 정보는 코드에 직접 노출하지 않음

• 운영환경에서는 Secret/Vault 등 보안 솔루션 활용 권장

• .env 파일은 개발 환경에서만 사용, 운영은 Secret/Vault 활용
  실전 예시:

• 환경 변수 설정 (개발 환경)

  1 2 3 4 5 6 7 8 9 10 11 12 13

  # .env.example (버전 관리에 포함) NODE_ENV=development PORT=3000 DATABASE_URL=mongodb://localhost:27017/myapp JWT_SECRET=your-jwt-secret-here API_KEY=your-api-key-here # .env (버전 관리에서 제외, .gitignore에 추가) NODE_ENV=development PORT=3000 DATABASE_URL=mongodb://localhost:27017/myapp_dev JWT_SECRET=super-secret-development-key API_KEY=dev-api-key-123

• 애플리케이션에서 환경 변수 사용

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

  // config.js require('dotenv').config(); const config = { port: process.env.PORT || 3000, nodeEnv: process.env.NODE_ENV || 'development', databaseUrl: process.env.DATABASE_URL, jwtSecret: process.env.JWT_SECRET, apiKey: process.env.API_KEY }; // 필수 환경 변수 검증 const requiredEnvVars = ['DATABASE_URL', 'JWT_SECRET']; requiredEnvVars.forEach(envVar => { if (!process.env[envVar]) { console.error(`❌ Required environment variable ${envVar} is missing`); process.exit(1); } }); module.exports = config;

• Kubernetes 에서의 설정 관리 (프로덕션 권장)

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38

  # ConfigMap for non-sensitive data apiVersion: v1 kind: ConfigMap metadata: name: app-config data: NODE_ENV: "production" PORT: "3000" --- # Secret for sensitive data apiVersion: v1 kind: Secret metadata: name: app-secrets type: Opaque data: DATABASE_URL: cG9zdGdyZXNxbDovL3VzZXI6cGFzc0BkYjoxMjM0NS9teWRi JWT_SECRET: c3VwZXItc2VjcmV0LWp3dC1rZXk= API_KEY: cHJvZC1hcGkta2V5LTQ1Ng== --- # Deployment using ConfigMap and Secret apiVersion: apps/v1 kind: Deployment metadata: name: myapp spec: template: spec: containers: - name: app image: myapp:latest envFrom: - configMapRef: name: app-config - secretRef: name: app-secrets

• Docker Compose 를 통한 환경별 설정

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

  # docker-compose.yml version: '3.8' services: web: build: . environment: - NODE_ENV=${NODE_ENV:-development} - PORT=${PORT:-3000} - DATABASE_URL=${DATABASE_URL} env_file: - .env depends_on: - db db: image: mongo:5 environment: MONGO_INITDB_DATABASE: myapp

Backing Services (지원 서비스)

원칙: 지원 서비스를 연결된 리소스로 취급한다.
설명: 데이터베이스, 캐시, 메시지 큐 등 네트워크로 접근하는 외부 리소스는 모두 ’ 지원 서비스 (Backing Service)’ 로 간주하고, 코드와 느슨하게 결합한다. 서비스의 위치나 종류가 변경되어도 환경변수만 바꾸면 되도록 설계한다.
특징:

• 데이터베이스, 캐시, 메시지 큐 등 외부 리소스

• 환경변수로 서비스 주소 관리

• 서비스 교체 시 코드 수정 불필요
  실전 예시:

• 지원 서비스 연결 설정

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32

  // services.js const config = require('./config'); // 데이터베이스 연결 const mongoose = require('mongoose'); mongoose.connect(config.databaseUrl); // Redis 캐시 연결 const redis = require('redis'); const redisClient = redis.createClient({ url: config.redisUrl }); // 메시지 큐 연결 const amqp = require('amqplib'); const messageQueue = amqp.connect(config.rabbitmqUrl); // 외부 API 클라이언트 const axios = require('axios'); const paymentAPI = axios.create({ baseURL: config.paymentServiceUrl, headers: { 'Authorization': `Bearer ${config.paymentApiKey}` } }); module.exports = { database: mongoose, cache: redisClient, messageQueue, paymentAPI };

• 서비스 추상화를 통한 교체 가능성 확보

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

  // database.js - 데이터베이스 추상화 class DatabaseService { constructor(connectionUrl) { if (connectionUrl.startsWith('mongodb://')) { this.client = require('./mongoAdapter')(connectionUrl); } else if (connectionUrl.startsWith('postgresql://')) { this.client = require('./postgresAdapter')(connectionUrl); } } async findUser(id) { return this.client.findUser(id); } async saveUser(userData) { return this.client.saveUser(userData); } } // 사용 const db = new DatabaseService(process.env.DATABASE_URL);

• Docker Compose 를 통한 로컬 지원 서비스 구성

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33

  version: '3.8' services: app: build: . environment: - DATABASE_URL=postgresql://user:pass@db:5432/myapp - REDIS_URL=redis://cache:6379 - RABBITMQ_URL=amqp://guest:guest@queue:5672 depends_on: - db - cache - queue db: image: postgres:15 environment: POSTGRES_DB: myapp POSTGRES_USER: user POSTGRES_PASSWORD: pass volumes: - postgres_data:/var/lib/postgresql/data cache: image: redis:7-alpine queue: image: rabbitmq:3-management environment: RABBITMQ_DEFAULT_USER: guest RABBITMQ_DEFAULT_PASS: guest volumes: postgres_data:

Build, Release, Run (빌드, 배포, 실행)

원칙: 빌드, 릴리즈, 실행 단계를 엄격하게 분리한다.
설명: 빌드 단계에서 코드를 컴파일하고, 릴리즈 단계에서 환경설정과 결합, 실행 단계에서 실제로 앱을 구동한다. 각 단계는 독립적으로 관리되어야 하며, CI/CD 파이프라인에서 자동화가 용이하다.
특징:

• 빌드/릴리즈/실행 단계 분리

• 각 단계별 자동화 및 버전 관리

• 롤백, 재배포 등 운영 편의성 향상

• GitHub Actions, Jenkins, ArgoCD 등 CI/CD 도구로 단계별 자동화
  실전 예시:

• GitHub Actions 를 통한 CI/CD 파이프라인

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46

  # .github/workflows/deploy.yml name: Build, Release, Deploy on: push: branches: [main] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 # 1. Build Stage - name: Build Docker image run: | docker build -t myapp:${{ github.sha }} . docker tag myapp:${{ github.sha }} myapp:latest - name: Push to registry run: | echo ${{ secrets.DOCKER_PASSWORD }} | docker login -u ${{ secrets.DOCKER_USERNAME }} --password-stdin docker push myapp:${{ github.sha }} docker push myapp:latest release: needs: build runs-on: ubuntu-latest steps: # 2. Release Stage - name: Create release run: | # 빌드된 이미지와 환경 설정을 결합하여 릴리스 생성 echo "Release ID: ${{ github.sha }}" > release-info.txt echo "Build: myapp:${{ github.sha }}" >> release-info.txt echo "Environment: production" >> release-info.txt deploy: needs: release runs-on: ubuntu-latest steps: # 3. Run Stage - name: Deploy to Kubernetes run: | kubectl set image deployment/myapp myapp=myapp:${{ github.sha }} kubectl rollout status deployment/myapp

• 로컬 개발을 위한 단순화된 파이프라인

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

  #!/bin/bash # deploy.sh set -e APP_NAME="myapp" VERSION=$(git rev-parse --short HEAD) REGISTRY="localhost:5000" echo "🔨 Build Stage" docker build -t ${APP_NAME}:${VERSION} . echo "📦 Release Stage" docker tag ${APP_NAME}:${VERSION} ${REGISTRY}/${APP_NAME}:${VERSION} docker tag ${APP_NAME}:${VERSION} ${REGISTRY}/${APP_NAME}:latest docker push ${REGISTRY}/${APP_NAME}:${VERSION} docker push ${REGISTRY}/${APP_NAME}:latest echo "🚀 Run Stage" kubectl set image deployment/${APP_NAME} ${APP_NAME}=${REGISTRY}/${APP_NAME}:${VERSION} kubectl rollout status deployment/${APP_NAME} echo "✅ Deployment completed: ${VERSION}"

Processes (프로세스)

원칙: 하나 이상의 상태 비저장 프로세스로 앱을 실행한다.
설명: 앱은 상태를 내부에 저장하지 않고, 모든 상태는 외부 지원 서비스 (데이터베이스, 캐시 등) 에 저장한다. 프로세스 간 상태 공유를 하지 않으며, 무상태 (stateless) 로 설계한다.
특징:

• 무상태 (stateless) 프로세스

• 상태 공유 금지, 외부 저장소 활용

• 수평 확장에 용이
  실전 예시:

• Express.js 에서 무상태 세션 관리

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52

  const express = require('express'); const session = require('express-session'); const RedisStore = require('connect-redis')(session); const redis = require('redis'); const app = express(); const redisClient = redis.createClient({ url: process.env.REDIS_URL }); // ❌ 잘못된 방식 - 메모리에 세션 저장 // app.use(session({ // secret: 'secret-key', // resave: false, // saveUninitialized: false // })); // ✅ 올바른 방식 - Redis에 세션 저장 app.use(session({ store: new RedisStore({ client: redisClient }), secret: process.env.SESSION_SECRET, resave: false, saveUninitialized: false, cookie: { secure: process.env.NODE_ENV === 'production', maxAge: 24 * 60 * 60 * 1000 // 24 hours } })); // 사용자 인증 상태도 JWT로 무상태화 const jwt = require('jsonwebtoken'); app.post('/login', async (req, res) => { const { username, password } = req.body; // 사용자 인증 로직 const user = await authenticateUser(username, password); if (!user) { return res.status(401).json({ error: 'Invalid credentials' }); } // JWT 토큰 생성 (무상태) const token = jwt.sign( { userId: user.id, username: user.username }, process.env.JWT_SECRET, { expiresIn: '24h' } ); res.json({ token, user: { id: user.id, username: user.username } }); }); app.listen(process.env.PORT || 3000);

• 파일 업로드 무상태 처리

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33

  const multer = require('multer'); const AWS = require('aws-sdk'); // ❌ 잘못된 방식 - 로컬 디스크에 저장 // const upload = multer({ dest: 'uploads/' }); // ✅ 올바른 방식 - 외부 저장소(S3) 직접 업로드 const s3 = new AWS.S3({ accessKeyId: process.env.AWS_ACCESS_KEY_ID, secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY, region: process.env.AWS_REGION }); const upload = multer({ storage: multer.memoryStorage(), limits: { fileSize: 10 * 1024 * 1024 } // 10MB }); app.post('/upload', upload.single('file'), async (req, res) => { try { const params = { Bucket: process.env.S3_BUCKET, Key: `uploads/${Date.now()}-${req.file.originalname}`, Body: req.file.buffer, ContentType: req.file.mimetype }; const result = await s3.upload(params).promise(); res.json({ url: result.Location }); } catch (error) { res.status(500).json({ error: 'Upload failed' }); } });

• Kubernetes 에서의 무상태 배포

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51

  apiVersion: apps/v1 kind: Deployment metadata: name: myapp spec: replicas: 3 selector: matchLabels: app: myapp template: metadata: labels: app: myapp spec: containers: - name: app image: myapp:latest ports: - containerPort: 3000 env: - name: REDIS_URL value: "redis://redis-service:6379" - name: JWT_SECRET valueFrom: secretKeyRef: name: app-secrets key: JWT_SECRET # 무상태를 위한 프로브 설정 livenessProbe: httpGet: path: /health port: 3000 initialDelaySeconds: 30 readinessProbe: httpGet: path: /ready port: 3000 initialDelaySeconds: 5 --- apiVersion: v1 kind: Service metadata: name: myapp-service spec: selector: app: myapp ports: - port: 80 targetPort: 3000 type: LoadBalancer

Port Binding (포트 바인딩)

원칙: 포트 바인딩을 통해 서비스를 외부에 공개한다.
설명: 앱은 자체적으로 포트를 바인딩해 웹 서버를 실행하며, 별도의 웹 서버 (Apache, Nginx) 없이 독립적으로 서비스가 가능하다. Kubernetes 에서는 Service, Ingress 등으로 외부 노출이 가능하다.
특징:

• 자체 포트에서 웹 서버 실행

• 포트 번호를 환경변수로 관리

• 독립 실행 및 외부 서비스 연동 가능
  실전 예시:

• Node.js Express 서버

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34

  const express = require('express'); const app = express(); // 환경 변수에서 포트 읽기, 기본값 3000 const PORT = process.env.PORT || 3000; app.get('/', (req, res) => { res.json({ message: 'Hello World!', port: PORT, pid: process.pid }); }); app.get('/health', (req, res) => { res.json({ status: 'healthy', timestamp: new Date().toISOString() }); }); // 서버 시작 시 바인딩된 포트 로깅 const server = app.listen(PORT, '0.0.0.0', () => { console.log(`🚀 Server is running on port ${PORT}`); console.log(`📍 Health check available at http://localhost:${PORT}/health`); }); // Graceful shutdown 지원 process.on('SIGTERM', () => { console.log('SIGTERM received, shutting down gracefully'); server.close(() => { console.log('Process terminated'); process.exit(0); }); }); module.exports = app;

• Python Flask 서버

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34

  from flask import Flask, jsonify import os import signal import sys app = Flask(__name__) PORT = int(os.getenv('PORT', 5000)) @app.route('/') def hello(): return jsonify({ 'message': 'Hello World!', 'port': PORT, 'pid': os.getpid() }) @app.route('/health') def health(): return jsonify({ 'status': 'healthy', 'timestamp': datetime.utcnow().isoformat() }) def signal_handler(sig, frame): print('Received shutdown signal, exiting gracefully...') sys.exit(0) if __name__ == '__main__': # 신호 핸들러 등록 signal.signal(signal.SIGTERM, signal_handler) signal.signal(signal.SIGINT, signal_handler) print(f'🚀 Server starting on port {PORT}') app.run(host='0.0.0.0', port=PORT, debug=False)

• Docker 컨테이너에서의 포트 바인딩

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

  FROM node:18-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY . . # 비root 사용자 생성 및 사용 RUN addgroup -g 1001 -S nodejs && \ adduser -S nextjs -u 1001 USER nextjs # 포트 환경 변수 설정 ENV PORT=3000 # 포트 노출 EXPOSE $PORT # 헬스체크 추가 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \ CMD curl -f http://localhost:$PORT/health || exit 1 CMD ["npm", "start"]

• Kubernetes 에서의 서비스 노출

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66

  apiVersion: apps/v1 kind: Deployment metadata: name: myapp spec: replicas: 2 selector: matchLabels: app: myapp template: metadata: labels: app: myapp spec: containers: - name: app image: myapp:latest ports: - name: http containerPort: 3000 protocol: TCP env: - name: PORT value: "3000" livenessProbe: httpGet: path: /health port: http readinessProbe: httpGet: path: /health port: http --- apiVersion: v1 kind: Service metadata: name: myapp-service spec: selector: app: myapp ports: - name: http port: 80 targetPort: http type: ClusterIP --- apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: myapp-ingress annotations: nginx.ingress.kubernetes.io/rewrite-target: / spec: rules: - host: myapp.example.com http: paths: - path: / pathType: Prefix backend: service: name: myapp-service port: number: 80

Concurrency (동시성)

원칙: 프로세스 모델을 통한 수평적 확장을 지원한다.
설명: 애플리케이션을 여러 프로세스 (웹, 워커 등) 로 분할해 동시성을 확보하고, 프로세스 매니저나 오케스트레이터 (Kubernetes 등) 로 확장한다.
특징:

• 프로세스별 역할 분리 (web, worker 등)

• 수평 확장 (HPA 등) 용이

• 각 프로세스 독립 실행

• Procfile 로 웹/워커 분리, Kubernetes Deployment 로 각각 확장
  실전 예시:

• Procfile 을 통한 프로세스 유형 정의

  1 2 3 4 5

  # Procfile web: node server.js worker: node worker.js scheduler: node scheduler.js release: node scripts/migrate.js

• Node.js 웹 프로세스 구현

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49

  // server.js - 웹 프로세스 const express = require('express'); const Queue = require('bull'); const app = express(); const PORT = process.env.PORT || 3000; // 작업 큐 연결 const emailQueue = new Queue('email processing', process.env.REDIS_URL); const imageQueue = new Queue('image processing', process.env.REDIS_URL); app.use(express.json()); // HTTP 요청 처리 (웹 프로세스의 역할) app.post('/api/users', async (req, res) => { try { const user = await createUser(req.body); // 이메일 발송을 워커 프로세스에 위임 await emailQueue.add('welcome-email', { userId: user.id, email: user.email }); res.status(201).json(user); } catch (error) { res.status(400).json({ error: error.message }); } }); app.post('/api/upload', async (req, res) => { try { const uploadResult = await handleUpload(req); // 이미지 처리를 워커 프로세스에 위임 await imageQueue.add('resize-image', { imageId: uploadResult.id, sizes: ['thumbnail', 'medium', 'large'] }); res.json(uploadResult); } catch (error) { res.status(500).json({ error: error.message }); } }); app.listen(PORT, () => { console.log(`🌐 Web process listening on port ${PORT}`); });

• Node.js 워커 프로세스 구현

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56

  // worker.js - 워커 프로세스 const Queue = require('bull'); const nodemailer = require('nodemailer'); const sharp = require('sharp'); // 큐 연결 const emailQueue = new Queue('email processing', process.env.REDIS_URL); const imageQueue = new Queue('image processing', process.env.REDIS_URL); // 이메일 발송 워커 emailQueue.process('welcome-email', async (job) => { const { userId, email } = job.data; console.log(`📧 Processing welcome email for user ${userId}`); const transporter = nodemailer.createTransporter({ host: process.env.SMTP_HOST, port: process.env.SMTP_PORT, auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS } }); await transporter.sendMail({ from: process.env.FROM_EMAIL, to: email, subject: 'Welcome to our platform!', html: `<h1>Welcome!</h1><p>Thank you for joining us.</p>` }); console.log(`✅ Welcome email sent to ${email}`); }); // 이미지 처리 워커 imageQueue.process('resize-image', async (job) => { const { imageId, sizes } = job.data; console.log(`🖼️ Processing image ${imageId} for sizes: ${sizes.join(', ')}`); const originalImage = await getImageById(imageId); for (const size of sizes) { const dimensions = getSizeDimensions(size); const resizedBuffer = await sharp(originalImage.buffer) .resize(dimensions.width, dimensions.height) .jpeg({ quality: 80 }) .toBuffer(); await saveResizedImage(imageId, size, resizedBuffer); } console.log(`✅ Image ${imageId} processed successfully`); }); console.log('👷 Worker processes started');

• 스케줄러 프로세스 구현

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37

  // scheduler.js - 스케줄러 프로세스 const cron = require('node-cron'); const Queue = require('bull'); const emailQueue = new Queue('email processing', process.env.REDIS_URL); const cleanupQueue = new Queue('cleanup tasks', process.env.REDIS_URL); // 매일 오전 9시에 일일 리포트 이메일 발송 cron.schedule('0 9 * * *', async () => { console.log('📊 Scheduling daily report emails'); const users = await getActiveUsers(); for (const user of users) { await emailQueue.add('daily-report', { userId: user.id, email: user.email }, { delay: Math.floor(Math.random() * 3600000) // 1시간 내 랜덤 지연 }); } }); // 매주 일요일 자정에 데이터 정리 cron.schedule('0 0 * * 0', async () => { console.log('🧹 Scheduling weekly cleanup'); await cleanupQueue.add('cleanup-old-logs', { olderThan: '30 days' }); await cleanupQueue.add('cleanup-temp-files', { olderThan: '7 days' }); }); console.log('⏰ Scheduler process started');

• Kubernetes 에서의 프로세스 유형별 배포

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119

  # Web 프로세스 배포 apiVersion: apps/v1 kind: Deployment metadata: name: myapp-web spec: replicas: 3 selector: matchLabels: app: myapp type: web template: metadata: labels: app: myapp type: web spec: containers: - name: web image: myapp:latest command: ["npm", "run", "start:web"] ports: - containerPort: 3000 env: - name: PROCESS_TYPE value: "web" resources: requests: memory: "128Mi" cpu: "100m" limits: memory: "256Mi" cpu: "200m" --- # Worker 프로세스 배포 apiVersion: apps/v1 kind: Deployment metadata: name: myapp-worker spec: replicas: 2 selector: matchLabels: app: myapp type: worker template: metadata: labels: app: myapp type: worker spec: containers: - name: worker image: myapp:latest command: ["npm", "run", "start:worker"] env: - name: PROCESS_TYPE value: "worker" resources: requests: memory: "256Mi" cpu: "200m" limits: memory: "512Mi" cpu: "500m" --- # 스케줄러 프로세스 배포 (단일 인스턴스) apiVersion: apps/v1 kind: Deployment metadata: name: myapp-scheduler spec: replicas: 1 selector: matchLabels: app: myapp type: scheduler template: metadata: labels: app: myapp type: scheduler spec: containers: - name: scheduler image: myapp:latest command: ["npm", "run", "start:scheduler"] env: - name: PROCESS_TYPE value: "scheduler" --- # HPA (Horizontal Pod Autoscaler) 설정 apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: myapp-web-hpa spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: myapp-web minReplicas: 2 maxReplicas: 10 metrics: - type: Resource resource: name: cpu target: type: Utilization averageUtilization: 70 - type: Resource resource: name: memory target: type: Utilization averageUtilization: 80