kt-event-marketing/design/backend/physical/physical-architecture-dev.md

# KT 이벤트 마케팅 서비스 - 개발환경 물리아키텍처 설계서

## 1. 개요

### 1.1 설계 목적

본 문서는 KT 이벤트 마케팅 서비스의 개발환경 물리 아키텍처를 정의합니다.

- **설계 범위**: 개발환경 전용 물리 인프라 설계
- **설계 목적**:
  - 비용 효율적인 개발환경 구축
  - 빠른 배포와 테스트 지원
  - 개발팀 생산성 최적화
- **대상 환경**: Azure 기반 개발환경 (Development)
- **대상 시스템**: 7개 마이크로서비스 + 백킹서비스

### 1.2 설계 원칙

개발환경에 적합한 4가지 핵심 설계 원칙을 정의합니다.

| 원칙 | 설명 | 적용 방법 |
|------|------|-----------|
| **MVP 우선** | 최소 기능으로 빠른 검증 | Pod 기반 백킹서비스, 단일 인스턴스 |
| **비용 최적화** | 개발환경 비용 최소화 | Basic 티어 서비스, 스팟 인스턴스 활용 |
| **개발 편의성** | 개발자 접근성 최대화 | 직접 접근 가능한 네트워크, 단순한 보안 |
| **단순성** | 복잡성 최소화 | 단일 VNet, 최소 보안 정책, 모니터링 생략 |

### 1.3 참조 아키텍처

| 아키텍처 문서 | 연관관계 | 참조 방법 |
|---------------|----------|-----------|
| [아키텍처 패턴](../pattern/architecture-pattern.md) | 마이크로서비스 패턴 기반 | 서비스 분리 및 통신 패턴 |
| [논리 아키텍처](../logical/) | 논리적 컴포넌트 구조 | 물리적 배치 및 연결 관계 |
| [데이터 설계서](../database/) | 데이터 저장소 요구사항 | PostgreSQL/Redis 구성 |
| [HighLevel 아키텍처](../high-level-architecture.md) | 전체 시스템 구조 | CI/CD 및 백킹서비스 선정 |

## 2. 개발환경 아키텍처 개요

### 2.1 환경 특성

| 특성 | 개발환경 설정값 | 근거 |
|------|----------------|------|
| **목적** | 개발자 기능 개발 및 통합 테스트 | 빠른 피드백 루프 |
| **사용자 규모** | 개발팀 10명 내외 | 소규모 동시 접근 |
| **가용성 목표** | 90% (업무시간 기준) | 야간/주말 중단 허용 |
| **확장성** | 수동 스케일링 | 예측 가능한 부하 |
| **보안 수준** | 기본 보안 (개발자 편의성 우선) | 접근 용이성 중요 |
| **데이터 보호** | 테스트 데이터 (실제 개인정보 없음) | 규제 요구사항 최소 |

### 2.2 전체 아키텍처

전체 시스템은 사용자 → Ingress → 마이크로서비스 → 백킹서비스 플로우로 구성됩니다.

- **아키텍처 다이어그램**: [physical-architecture-dev.mmd](./physical-architecture-dev.mmd)
- **네트워크 다이어그램**: [network-dev.mmd](./network-dev.mmd)

**주요 컴포넌트**:
- **Frontend**: 개발자 및 QA팀 접근
- **Kubernetes Ingress**: NGINX 기반 라우팅
- **7개 마이크로서비스**: user, event, content, ai, participation, analytics, distribution
- **PostgreSQL Pod**: 통합 데이터베이스
- **Redis Pod**: 캐시 및 세션 저장소
- **Azure Service Bus**: 비동기 메시징 (Basic 티어)

## 3. 컴퓨팅 아키텍처

### 3.1 Kubernetes 클러스터 구성

#### 3.1.1 클러스터 설정

| 설정 항목 | 설정값 | 설명 |
|-----------|--------|------|
| **Kubernetes 버전** | 1.28.x | 안정된 최신 버전 |
| **서비스 계층** | Free 티어 | 개발환경 비용 절약 |
| **네트워크 플러그인** | Azure CNI | Azure 네이티브 통합 |
| **DNS** | CoreDNS | 기본 DNS 서비스 |
| **RBAC** | 활성화 | 기본 보안 설정 |
| **Pod Security** | 기본 설정 | 개발 편의성 우선 |
| **Ingress Controller** | NGINX | 단순하고 가벼운 설정 |

#### 3.1.2 노드 풀 구성

| 노드 풀 | 인스턴스 크기 | 노드 수 | 스케일링 | 가용영역 | 가격 정책 |
|---------|---------------|---------|----------|----------|----------|
| **Default** | Standard_B2s | 2-4 노드 | 수동 | Single Zone | 스팟 인스턴스 50% |
| **사양** | 2 vCPU, 4GB RAM | 최소 2, 최대 4 | kubectl 수동 확장 | Korea Central | 비용 우선 |

### 3.2 서비스별 리소스 할당

#### 3.2.1 애플리케이션 서비스

| 서비스명 | CPU Requests | CPU Limits | Memory Requests | Memory Limits | Replicas |
|----------|--------------|------------|-----------------|---------------|----------|
| **user-service** | 100m | 200m | 128Mi | 256Mi | 1 |
| **event-service** | 100m | 200m | 128Mi | 256Mi | 1 |
| **content-service** | 100m | 200m | 128Mi | 256Mi | 1 |
| **ai-service** | 100m | 300m | 256Mi | 512Mi | 1 |
| **participation-service** | 100m | 200m | 128Mi | 256Mi | 1 |
| **analytics-service** | 100m | 200m | 128Mi | 256Mi | 1 |
| **distribution-service** | 100m | 200m | 128Mi | 256Mi | 1 |

#### 3.2.2 백킹 서비스

| 서비스명 | CPU Requests | CPU Limits | Memory Requests | Memory Limits | Storage |
|----------|--------------|------------|-----------------|---------------|---------|
| **postgresql** | 200m | 500m | 512Mi | 1Gi | 20Gi (Premium SSD) |
| **redis** | 100m | 200m | 128Mi | 256Mi | 1Gi (메모리 기반) |

#### 3.2.3 스토리지 클래스 구성

| 스토리지 클래스 | 종류 | 성능 | 용도 | 비용 |
|----------------|------|------|------|------|
| **managed-premium** | Azure Premium SSD | 최대 5,000 IOPS | PostgreSQL 데이터 | 중간 |
| **managed** | Azure Standard SSD | 최대 2,000 IOPS | 로그 및 임시 데이터 | 저비용 |

## 4. 네트워크 아키텍처

### 4.1 네트워크 구성

#### 4.1.1 네트워크 토폴로지

**네트워크 구성**:
- **VNet 주소 공간**: 10.0.0.0/16
- **AKS 서브넷**: 10.0.1.0/24 (사용자, 서비스, 백킹서비스 통합)
- **Service Bus 서브넷**: 10.0.2.0/24 (Azure Service Bus Basic)

**네트워크 다이어그램**: [network-dev.mmd](./network-dev.mmd)

#### 4.1.2 네트워크 보안

| 정책 유형 | 설정 | 설명 |
|-----------|------|------|
| **Network Policy** | 기본 허용 | 개발 편의성 우선 |
| **접근 제한** | 개발팀 IP 대역만 허용 | 기본 보안 유지 |
| **포트 정책** | 표준 HTTP/HTTPS 포트 | 80, 443, 8080-8087 |

### 4.2 서비스 디스커버리

| 서비스명 | 내부 DNS 주소 | 포트 | 용도 |
|----------|---------------|------|------|
| **user-service** | user-service:8080 | 8080 | 사용자 관리 API |
| **event-service** | event-service:8080 | 8080 | 이벤트 관리 API |
| **content-service** | content-service:8080 | 8080 | 콘텐츠 관리 API |
| **ai-service** | ai-service:8080 | 8080 | AI 추천 API |
| **participation-service** | participation-service:8080 | 8080 | 참여 관리 API |
| **analytics-service** | analytics-service:8080 | 8080 | 분석 API |
| **distribution-service** | distribution-service:8080 | 8080 | 배포 관리 API |
| **postgresql** | postgresql:5432 | 5432 | 주 데이터베이스 |
| **redis** | redis:6379 | 6379 | 캐시 및 세션 |

## 5. 데이터 아키텍처

### 5.1 데이터베이스 구성

#### 5.1.1 주 데이터베이스 Pod 구성

| 설정 항목 | 설정값 | 설명 |
|-----------|--------|------|
| **컨테이너 이미지** | postgres:15-alpine | 경량화된 PostgreSQL |
| **CPU** | 200m requests, 500m limits | 개발환경 적정 사양 |
| **Memory** | 512Mi requests, 1Gi limits | 기본 워크로드 처리 |
| **Storage** | 20Gi Premium SSD | Azure Disk 연동 |
| **백업** | 수동 스냅샷 | 주간 단위 수동 백업 |
| **HA 구성** | 단일 인스턴스 | 비용 최적화 |

#### 5.1.2 캐시 Pod 구성

| 설정 항목 | 설정값 | 설명 |
|-----------|--------|------|
| **컨테이너 이미지** | redis:7-alpine | 경량화된 Redis |
| **CPU** | 100m requests, 200m limits | 가벼운 캐시 워크로드 |
| **Memory** | 128Mi requests, 256Mi limits | 기본 캐시 용량 |
| **Storage** | 1Gi (선택적) | 영구 저장이 필요한 경우만 |
| **설정** | Default 설정 | 특별한 튜닝 없음 |

### 5.2 데이터 관리 전략

#### 5.2.1 데이터 초기화

```yaml
# 데이터 초기화 Job 예시
apiVersion: batch/v1
kind: Job
metadata:
  name: db-init-job
spec:
  template:
    spec:
      containers:
      - name: db-init
        image: postgres:15-alpine
        command: ["/bin/sh"]
        args:
          - -c
          - |
            psql -h postgresql -U postgres -d kt_event_marketing << EOF
            -- 테스트 데이터 생성
            INSERT INTO users (username, email) VALUES ('test_user', 'test@example.com');
            INSERT INTO stores (name, address) VALUES ('테스트 매장', '서울시 강남구');
            EOF
      restartPolicy: OnFailure
```

**실행 절차**:
1. `kubectl apply -f db-init-job.yaml`
2. `kubectl logs job/db-init-job` 실행 결과 확인
3. `kubectl delete job db-init-job` 정리

#### 5.2.2 백업 전략

| 서비스 | 백업 방법 | 주기 | 보존 기간 | 복구 절차 |
|--------|-----------|------|-----------|-----------|
| **PostgreSQL** | Azure Disk 스냅샷 | 주 1회 (금요일) | 4주 | 스냅샷 복원 |
| **Redis** | RDB 덤프 | 일 1회 | 1주 | 덤프 파일 복원 |

## 6. 메시징 아키텍처

### 6.1 Message Queue 구성

#### 6.1.1 Basic Tier 설정

| 설정 항목 | 설정값 | 설명 |
|-----------|--------|------|
| **서비스** | Azure Service Bus Basic | 개발환경 최소 비용 |
| **네임스페이스** | kt-event-dev | 개발 전용 네임스페이스 |
| **큐 개수** | 3개 | ai-schedule, location-search, notification |
| **메시지 크기** | 최대 256KB | Basic 티어 제한 |
| **TTL** | 14일 | 기본 설정 |

#### 6.1.2 연결 설정

| 설정 항목 | 설정값 | 설명 |
|-----------|--------|------|
| **인증** | Connection String | 개발환경 단순 인증 |
| **연결 풀** | 기본 설정 | 특별한 튜닝 없음 |
| **재시도 정책** | 3회 재시도 | 기본 resilience |
| **배치 처리** | 비활성화 | 단순한 메시지 처리 |

## 7. 보안 아키텍처

### 7.1 개발환경 보안 정책

#### 7.1.1 기본 보안 설정

| 보안 계층 | 설정값 | 수준 | 관리 대상 시크릿 |
|-----------|--------|------|-----------------|
| **네트워크** | 기본 NSG | 기본 | - |
| **클러스터** | RBAC 활성화 | 기본 | ServiceAccount 토큰 |
| **애플리케이션** | 기본 설정 | 기본 | DB 연결 정보 |
| **데이터** | 전송 암호화만 | 기본 | Redis 비밀번호 |

#### 7.1.2 시크릿 관리

| 시크릿 유형 | 저장 방식 | 순환 정책 | 저장소 |
|-------------|-----------|-----------|--------|
| **DB 비밀번호** | Kubernetes Secret | 수동 | etcd |
| **API 키** | Kubernetes Secret | 월 1회 | etcd |
| **Service Bus** | Connection String | 수동 | etcd |

### 7.2 Network Policies

#### 7.2.1 기본 정책

```yaml
# 기본적으로 모든 통신 허용 (개발 편의성)
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-all-dev
spec:
  podSelector: {}
  policyTypes:
  - Ingress
  - Egress
  ingress:
  - {}
  egress:
  - {}
```

## 8. 모니터링 및 로깅

### 8.1 기본 모니터링

#### 8.1.1 Kubernetes 기본 모니터링

| 컴포넌트 | 설정 | 임계값 |
|----------|------|--------|
| **kubectl top** | 기본 메트릭 | CPU 80%, Memory 80% |
| **기본 알림** | 비활성화 | 개발환경 알림 불필요 |

#### 8.1.2 애플리케이션 모니터링

| 메트릭 유형 | 수집 방법 | 설정 |
|-------------|-----------|------|
| **헬스체크** | Spring Actuator | /actuator/health |
| **메트릭** | 기본 로그 | stdout 로그만 |

### 8.2 로깅

#### 8.2.1 로그 수집

| 로그 유형 | 수집 방식 | 저장 방식 | 보존 기간 | 로그 레벨 |
|-----------|-----------|-----------|-----------|-----------|
| **애플리케이션** | stdout | kubectl logs | 7일 | DEBUG |
| **시스템** | kubelet | 로컬 | 3일 | INFO |

## 9. 배포 관련 컴포넌트

| 컴포넌트 | 역할 | 설정 |
|----------|------|------|
| **GitHub Actions** | CI/CD 파이프라인 | 기본 워크플로우 |
| **Docker Registry** | 컨테이너 이미지 저장소 | Azure Container Registry |
| **kubectl** | 배포 도구 | 수동 배포 |
| **IntelliJ 프로파일** | 로컬 개발 | 서비스별 실행 프로파일 |

## 10. 비용 최적화

### 10.1 개발환경 비용 구조

#### 10.1.1 주요 비용 요소

| 구성요소 | 사양 | 월간 예상 비용 (USD) | 절약 방안 |
|----------|------|---------------------|-----------|
| **AKS 클러스터** | Free 티어 | $0 | Free 티어 활용 |
| **VM 노드** | 2 x Standard_B2s (스팟 50%) | $50 | 스팟 인스턴스 활용 |
| **Storage** | 50Gi Premium SSD | $10 | 최소 필요 용량만 |
| **Service Bus** | Basic 티어 | $5 | Basic 티어 사용 |
| **네트워크** | Standard Load Balancer | $15 | 기본 설정 |
| **총 예상 비용** | - | **$80** | - |

#### 10.1.2 비용 절약 전략

| 영역 | 절약 방안 | 절약률 |
|------|-----------|--------|
| **컴퓨팅** | 스팟 인스턴스 50% 혼합 | 25% |
| **스토리지** | 최소 필요 용량만 할당 | 30% |
| **네트워킹** | 단일 VNet 구성 | 20% |

## 11. 개발환경 운영 가이드

### 11.1 일상 운영

#### 11.1.1 환경 시작/종료

```bash
# 클러스터 시작 (매일 오전)
az aks start --resource-group kt-event-dev --name kt-event-aks-dev

# 서비스 상태 확인
kubectl get pods -A
kubectl get svc

# 클러스터 종료 (매일 저녁)
az aks stop --resource-group kt-event-dev --name kt-event-aks-dev
```

#### 11.1.2 데이터 관리

```bash
# PostgreSQL 데이터 백업
kubectl exec -it postgresql-0 -- pg_dump -U postgres kt_event_marketing > backup.sql

# Redis 데이터 백업
kubectl exec -it redis-0 -- redis-cli --rdb dump.rdb

# 데이터 복원
kubectl exec -i postgresql-0 -- psql -U postgres -d kt_event_marketing < backup.sql
```

### 11.2 트러블슈팅

#### 11.2.1 일반적인 문제 해결

| 문제 유형 | 원인 | 해결방안 | 예방법 |
|-----------|------|----------|--------|
| **Pod 시작 실패** | 리소스 부족 | 노드 스케일 업 | 리소스 모니터링 |
| **DB 연결 실패** | 네트워크 정책 | Service 확인 | 헬스체크 활성화 |
| **Service Bus 연결 오류** | 인증 정보 | Secret 재생성 | 정기 키 순환 |

## 12. 개발환경 특성 요약

**핵심 설계 원칙**:
- **비용 우선**: 개발환경은 최소 비용으로 구성하여 월 $80 이하 목표
- **단순성**: 복잡한 HA 구성 없이 단순한 아키텍처 유지
- **개발 편의성**: 개발자가 쉽게 접근하고 디버깅할 수 있는 환경

**주요 제약사항**:
- **가용성**: 90% (업무시간 기준), 야간/주말 중단 허용
- **확장성**: 수동 스케일링으로 예측 가능한 부하만 처리
- **보안**: 기본 보안 설정으로 개발 편의성 우선

**최적화 목표**:
- **빠른 배포**: 5분 이내 전체 환경 배포 완료
- **비용 효율**: 월 $80 이하 운영 비용 유지
- **개발 생산성**: 로컬 개발과 유사한 편의성 제공

---

**문서 버전**: v1.0
**최종 수정일**: 2025-10-29
**작성자**: System Architect (박영자 "전문 아키텍트")