phonebill/design/backend/physical/physical-architecture-dev.md

물리 아키텍처 설계서 - 개발환경

1. 개요

1.1 설계 목적

• 통신요금 관리 서비스의 개발환경 물리 아키텍처 설계
• MVP 단계의 빠른 개발과 검증을 위한 최소 구성
• 비용 효율성과 개발 편의성 우선

1.2 설계 원칙

• MVP 우선: 빠른 개발과 검증을 위한 최소 구성
• 비용 최적화: Spot Instances, Pod 기반 백킹서비스 활용
• 개발 편의성: 복잡한 설정 최소화, 빠른 배포
• 단순성: 운영 복잡도 최소화

1.3 참조 아키텍처

• 마스터 아키텍처: design/backend/physical/physical-architecture.md
• HighLevel아키텍처정의서: design/high-level-architecture.md
• 논리아키텍처: design/backend/logical/logical-architecture.md
• 유저스토리: design/userstory.md

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

2.1 환경 특성

• 목적: 빠른 개발과 검증
• 사용자: 개발팀 (5명)
• 가용성: 95% (월 36시간 다운타임 허용)
• 확장성: 제한적 (고정 리소스)
• 보안: 기본 보안 (복잡한 보안 설정 최소화)

2.2 전체 아키텍처

📄 개발환경 물리 아키텍처 다이어그램

주요 구성 요소:

• NGINX Ingress Controller → AKS 기본 클러스터
• 애플리케이션 Pod: Auth, Bill-Inquiry, Product-Change, KOS-Mock Service
• 백킹서비스 Pod: PostgreSQL (Local Storage), Redis (Memory Only)

3. 컴퓨팅 아키텍처

3.1 Azure Kubernetes Service (AKS) 구성

3.1.1 클러스터 설정

설정 항목	값	설명
Kubernetes 버전	1.29	안정화된 최신 버전
서비스 계층	Basic	비용 최적화
Network Plugin	Azure CNI	Azure 네이티브 네트워킹
Network Policy	Kubernetes Network Policies	기본 Pod 통신 제어
Ingress Controller	NGINX Ingress Controller	오픈소스 Ingress
DNS	CoreDNS	클러스터 DNS

3.1.2 노드 풀 구성

설정 항목	값	설명
VM 크기	Standard_B2s	2 vCPU, 4GB RAM
노드 수	2	고정 노드 수
자동 스케일링	Disabled	비용 절약을 위한 고정 크기
최대 Pod 수	30	노드당 최대 Pod
가용 영역	Zone-1	단일 영역 (비용 절약)
가격 정책	Spot Instance	70% 비용 절약

3.2 서비스별 리소스 할당

3.2.1 애플리케이션 서비스

서비스	CPU Requests	Memory Requests	CPU Limits	Memory Limits	Replicas
Auth Service	50m	128Mi	200m	256Mi	1
Bill-Inquiry Service	100m	256Mi	500m	512Mi	1
Product-Change Service	100m	256Mi	500m	512Mi	1
KOS-Mock Service	50m	128Mi	200m	256Mi	1

3.2.2 백킹 서비스

서비스	CPU Requests	Memory Requests	CPU Limits	Memory Limits	Storage
PostgreSQL	500m	1Gi	1000m	2Gi	20GB (Azure Disk Standard)
Redis	100m	256Mi	500m	1Gi	Memory Only

3.2.3 스토리지 클래스 구성

스토리지 클래스	제공자	성능	용도	백업 정책
managed-standard	Azure Disk	Standard HDD	개발용 데이터 저장	수동 백업
managed-premium	Azure Disk	Premium SSD	미사용 (비용 절약)	-

4. 네트워크 아키텍처

4.1 네트워크 구성

4.1.1 네트워크 토폴로지

📄 개발환경 네트워크 다이어그램

네트워크 구성요소	주소 대역	용도	특별 설정
Virtual Network	phonebill-vnet-dev	전체 네트워크	Azure CNI 사용
Public Subnet	10.0.1.0/24	Load Balancer, Ingress	인터넷 연결
Application Subnet	10.0.2.0/24	애플리케이션 Pod	Private 통신
Data Subnet	10.0.3.0/24	데이터베이스, 캐시	제한적 접근
Management Subnet	10.0.4.0/24	모니터링, 관리	개발용 도구

4.1.2 네트워크 보안

기본 Network Policy:

정책 유형	설정	설명
Default Policy	ALLOW_ALL_NAMESPACES	개발 편의성을 위한 허용적 정책
Complexity Level	Basic	단순한 보안 구성

Database 접근 제한:

설정 항목	값	설명
허용 대상	Application Tier Pods	tier: application 레이블
프로토콜	TCP	데이터베이스 연결
포트	5432, 6379	PostgreSQL, Redis 포트

4.2 서비스 디스커버리

서비스	내부 주소	포트	용도
Auth Service	auth-service.phonebill-dev.svc.cluster.local	8080	사용자 인증 API
Bill-Inquiry Service	bill-inquiry-service.phonebill-dev.svc.cluster.local	8080	요금 조회 API
Product-Change Service	product-change-service.phonebill-dev.svc.cluster.local	8080	상품 변경 API
PostgreSQL	postgresql.phonebill-dev.svc.cluster.local	5432	메인 데이터베이스
Redis	redis.phonebill-dev.svc.cluster.local	6379	캐시 서버

5. 데이터 아키텍처

5.1 데이터베이스 구성

5.1.1 주 데이터베이스 Pod 구성

기본 설정:

설정 항목	값	설명
컨테이너 이미지	bitnami/postgresql:16	안정화된 PostgreSQL 16
CPU 요청	500m	기본 CPU 할당
Memory 요청	1Gi	기본 메모리 할당
CPU 제한	1000m	최대 CPU 사용량
Memory 제한	2Gi	최대 메모리 사용량

스토리지 구성:

설정 항목	값	설명
스토리지 클래스	managed-standard	Azure Disk Standard
스토리지 크기	20Gi	개발용 충분한 용량
마운트 경로	/bitnami/postgresql	데이터 저장 경로
백업 전략	Azure Backup	일일 자동 백업

데이터베이스 설정값:

설정 항목	값	설명
최대 연결 수	100	동시 연결 제한
Shared Buffers	256MB	공유 버퍼 크기
Effective Cache Size	1GB	효과적 캐시 크기
Work Memory	4MB	작업 메모리

5.1.2 캐시 Pod 구성

기본 설정:

설정 항목	값	설명
컨테이너 이미지	bitnami/redis:7.2	최신 안정 Redis 버전
CPU 요청	100m	기본 CPU 할당
Memory 요청	256Mi	기본 메모리 할당
CPU 제한	500m	최대 CPU 사용량
Memory 제한	1Gi	최대 메모리 사용량

메모리 설정:

설정 항목	값	설명
데이터 지속성	Disabled	개발용, 재시작 시 데이터 손실 허용
최대 메모리	512MB	메모리 사용 제한
메모리 정책	allkeys-lru	LRU 방식 캐시 제거
TTL 설정	30분	기본 캐시 만료 시간

5.2 데이터 관리 전략

5.2.1 데이터 초기화

Kubernetes Job을 통한 데이터 초기화:

• 데이터베이스 스키마 생성: auth, bill_inquiry, product_change 스키마
• 초기 사용자 데이터: 테스트 계정 생성 (admin, developer, tester)
• 기본 상품 데이터: KOS 연동을 위한 샘플 상품 정보
• 권한 설정: 개발팀용 기본 권한 설정

실행 절차:

# 데이터 초기화 Job
apiVersion: batch/v1
kind: Job
metadata:
  name: data-init-job
spec:
  template:
    spec:
      containers:
      - name: init-container
        image: bitnami/postgresql:16
        env:
        - name: PGPASSWORD
          valueFrom:
            secretKeyRef:
              name: postgresql-secret
              key: postgres-password
        command: ["/bin/bash"]
        args:
        - -c
        - |
          psql -h postgresql -U postgres -f /scripts/init-schema.sql
          psql -h postgresql -U postgres -f /scripts/sample-data.sql
      restartPolicy: OnFailure

검증 방법:

# 초기화 확인
kubectl exec -it postgresql-0 -- psql -U postgres -c "SELECT COUNT(*) FROM users;"
kubectl exec -it postgresql-0 -- psql -U postgres -c "SELECT COUNT(*) FROM products;"

5.2.2 백업 전략

서비스	백업 방법	주기	보존 전략	참고사항
PostgreSQL	Azure Disk Snapshot	일일	7일 보관	개발용 데이터 자동 백업
Redis	없음	-	메모리 전용	재시작 시 캐시 재구성
Application Logs	Azure Monitor Logs	실시간	14일 보관	디버깅용 로그

6. KOS-Mock 서비스

6.1 KOS-Mock 구성

6.1.1 서비스 설정

KOS-Mock 서비스 구성:

설정 항목	값	설명
컨테이너 이미지	kos-mock:latest	개발환경용 Mock 서비스
포트	8080	HTTP REST API
헬스체크	/health	서비스 상태 확인
데이터베이스	PostgreSQL	Mock 데이터 저장

제공 API:

API 경로	메소드	용도	응답 시간
/api/v1/bill-inquiry	POST	요금 조회 Mock	100-500ms
/api/v1/product-change	POST	상품 변경 Mock	200-1000ms
/api/v1/customer-info	GET	고객 정보 Mock	50-200ms
/health	GET	헬스 체크	10ms

6.1.2 Mock 데이터 설정

Mock 응답 패턴:

응답 타입	비율	지연시간	용도
성공 응답	80%	100-300ms	정상 케이스 테스트
지연 응답	15%	1-3초	타임아웃 테스트
오류 응답	5%	100ms	오류 처리 테스트

7. 보안 아키텍처

7.1 개발환경 보안 정책

7.1.1 기본 보안 설정

보안 계층별 설정값:

계층	설정	수준	설명
L4 네트워크 보안	Network Security Group	기본	기본 Azure NSG 규칙
L3 클러스터 보안	Kubernetes RBAC	기본	개발팀 전체 접근 권한
L2 애플리케이션 보안	JWT 인증	기본	개발용 고정 시크릿
L1 데이터 보안	TLS 1.2	기본	Pod 간 암호화 통신

관리 대상 시크릿:

시크릿 이름	용도	순환 정책	저장 위치
postgresql-secret	PostgreSQL 접근	수동	Kubernetes Secret
redis-secret	Redis 접근	수동	Kubernetes Secret
jwt-signing-key	JWT 토큰 서명	수동	Kubernetes Secret
kos-mock-config	KOS-Mock 설정	수동	Kubernetes ConfigMap

7.1.2 시크릿 관리

시크릿 관리 전략:

설정 항목	값	설명
관리 방식	Kubernetes Secrets	기본 K8s 내장 방식
암호화 방식	etcd 암호화	클러스터 레벨 암호화
접근 제어	RBAC	네임스페이스별 접근 제어
감사 로그	Enabled	Secret 접근 로그 기록

7.2 Network Policies

7.2.1 기본 정책

Network Policy 설정:

설정 항목	값	설명
Policy 이름	dev-basic-policy	개발환경 기본 정책
Pod 선택자	app=phonebill	애플리케이션 Pod 대상
Ingress 규칙	동일 네임스페이스 허용	개발환경 편의상 허용적 정책
Egress 규칙	외부 시스템 허용	KOS-Mock 서비스 접근 허용

8. 모니터링 및 로깅

8.1 기본 모니터링

8.1.1 Kubernetes 기본 모니터링

모니터링 스택 구성:

구성요소	도구	상태	설명
메트릭 서버	Metrics Server	Enabled	기본 리소스 메트릭 수집
대시보드	Kubernetes Dashboard	Enabled	웹 기반 클러스터 관리
로그 수집	kubectl logs	Manual	수동 로그 확인

기본 알림 임계값:

알림 유형	임계값	대응 방안	알림 대상
Pod Crash Loop	5회 연속 재시작	개발자 Slack 알림	개발팀
Node Not Ready	5분 이상	노드 상태 점검	인프라팀
High Memory Usage	85% 이상	리소스 할당 검토	개발팀
Disk Usage	80% 이상	스토리지 정리	인프라팀

8.1.2 애플리케이션 모니터링

헬스체크 설정:

설정 항목	값	설명
Liveness Probe	/actuator/health/liveness	Spring Boot Actuator
Readiness Probe	/actuator/health/readiness	트래픽 수신 준비 상태
체크 주기	30초	상태 확인 간격
타임아웃	5초	응답 대기 시간

수집 메트릭 유형:

메트릭 유형	도구	용도	보존 기간
JVM Metrics	Micrometer	가상머신 성능 모니터링	7일
HTTP Request Metrics	Micrometer	API 요청 통계	7일
Database Pool Metrics	HikariCP	DB 연결 풀 상태	7일
Custom Business Metrics	Micrometer	비즈니스 지표	7일

8.2 로깅

8.2.1 로그 수집

로그 수집 방식:

설정 항목	값	설명
수집 방식	stdout/stderr	표준 출력으로 로그 전송
저장 방식	Azure Container Logs	AKS 기본 로그 저장소
보존 기간	7일	개발환경 단기 보존
로그 형식	JSON	구조화된 로그 형식

로그 레벨별 설정:

로거 유형	레벨	설명
Root Logger	INFO	전체 시스템 기본 레벨
Application Logger	DEBUG	개발용 상세 로그
Database Logger	INFO	데이터베이스 쿼리 로그
External API Logger	DEBUG	외부 시스템 연동 로그

9. 배포 관련 컴포넌트

컴포넌트 유형	컴포넌트	역할	설정
Container Registry	Azure Container Registry Basic	이미지 저장소	phonebilldev.azurecr.io
CI	GitHub Actions	지속적 통합	코드 빌드, 테스트, 이미지 빌드
CD	ArgoCD	GitOps 배포	자동 배포, 롤백
패키지 관리	Helm	Kubernetes 패키지 관리	values-dev.yaml 설정
환경별 설정	ConfigMap	환경 변수 관리	개발환경 전용 설정
시크릿 관리	Kubernetes Secret	민감 정보 관리	DB 연결 정보 등

10. 비용 최적화

10.1 개발환경 비용 구조

10.1.1 주요 비용 요소

구성요소	사양	월간 예상 비용 (USD)	절약 방안
AKS 클러스터	관리형 서비스	$73	기본 서비스 계층 사용
노드 풀 (VM)	Standard_B2s × 2	$60	Spot Instance 적용
Azure Disk	Standard 20GB × 2	$5	개발용 최소 용량
Load Balancer	Basic	$18	기본 계층 사용
Container Registry	Basic	$5	개발용 기본 계층
네트워킹	데이터 전송	$10	단일 리전 사용
총합		$171	Spot Instance로 $42 절약 가능

10.1.2 비용 절약 전략

컴퓨팅 영역별 절약 방안:

절약 방안	절약률	적용 방법	예상 절약 금액
Spot Instances	70%	노드 풀에 Spot VM 사용	$42/월
비업무시간 자동 종료	50%	야간/주말 클러스터 스케일다운	$30/월
리소스 Right-sizing	20%	requests/limits 최적화	$12/월

스토리지 영역별 절약 방안:

절약 방안	절약률	적용 방법	예상 절약 금액
Standard Disk 사용	60%	Premium 대신 Standard 사용	이미 적용
스토리지 크기 최적화	30%	사용량 모니터링 후 크기 조정	$2/월

네트워킹 영역별 절약 방안:

절약 방안	절약률	적용 방법	예상 절약 금액
Basic Load Balancer	50%	Standard 대신 Basic 사용	이미 적용
단일 리전 배포	100%	데이터 전송 비용 최소화	$5/월

11. 개발환경 운영 가이드

11.1 일상 운영

11.1.1 환경 시작/종료

환경 시작 절차:

# 클러스터 스케일업
az aks scale --resource-group phonebill-dev-rg --name phonebill-dev-aks --node-count 2

# 애플리케이션 시작
kubectl scale deployment auth-service --replicas=1
kubectl scale deployment bill-inquiry-service --replicas=1
kubectl scale deployment product-change-service --replicas=1

# 백킹 서비스 시작
kubectl scale statefulset postgresql --replicas=1
kubectl scale deployment redis --replicas=1

# 상태 확인
kubectl get pods -w

환경 종료 절차 (야간/주말):

# 애플리케이션 종료
kubectl scale deployment --replicas=0 --all

# 백킹 서비스는 데이터 보존을 위해 유지
# 클러스터 스케일다운 (비용 절약)
az aks scale --resource-group phonebill-dev-rg --name phonebill-dev-aks --node-count 1

11.1.2 데이터 관리

개발 데이터 초기화:

# 데이터 초기화 Job 실행
kubectl apply -f k8s/jobs/data-init-job.yaml

# 초기화 진행 상황 확인
kubectl logs -f job/data-init-job

# 데이터 초기화 확인
kubectl exec -it postgresql-0 -- psql -U postgres -c "SELECT COUNT(*) FROM users;"

개발 데이터 백업:

# 데이터베이스 백업
kubectl exec postgresql-0 -- pg_dump -U postgres phonebill > backup-$(date +%Y%m%d).sql

# Azure Disk 스냅샷 생성
az snapshot create \
  --resource-group phonebill-dev-rg \
  --name postgresql-snapshot-$(date +%Y%m%d) \
  --source postgresql-disk

데이터 복원:

# SQL 파일로부터 복원
kubectl exec -i postgresql-0 -- psql -U postgres phonebill < backup.sql

# 스냅샷으로부터 디스크 복원
az disk create \
  --resource-group phonebill-dev-rg \
  --name postgresql-restored-disk \
  --source postgresql-snapshot-20250108

11.2 트러블슈팅

11.2.1 일반적인 문제 해결

문제 유형	원인	해결방안	예방법
Pod Pending	리소스 부족	노드 추가 또는 리소스 조정	리소스 사용량 모니터링
Database Connection Failed	PostgreSQL Pod 재시작	Pod 로그 확인 및 재시작	Health Check 강화
Service Unavailable	Ingress 설정 오류	Ingress 규칙 확인 및 수정	배포 전 설정 검증
Out of Memory	메모리 한계 초과	Memory Limits 증대	메모리 사용 패턴 분석
Disk Full	로그 파일 과다	로그 정리 및 보존 정책 수정	로그 순환 정책 설정

문제 해결 절차:

# 1. Pod 상태 확인
kubectl get pods -o wide
kubectl describe pod <pod-name>

# 2. 로그 확인
kubectl logs <pod-name> --tail=50

# 3. 리소스 사용량 확인
kubectl top pods
kubectl top nodes

# 4. 서비스 연결 확인
kubectl get svc
kubectl describe svc <service-name>

# 5. 네트워크 정책 확인
kubectl get networkpolicy
kubectl describe networkpolicy <policy-name>

12. 개발환경 특성 요약

핵심 설계 원칙: 빠른 개발 > 비용 효율 > 단순성 > 실험성
주요 제약사항: 95% 가용성, 제한적 확장성, 기본 보안 수준
최적화 목표: 개발팀 생산성 향상, 빠른 피드백 루프, 비용 효율적 운영

이 개발환경은 통신요금 관리 서비스의 빠른 MVP 개발과 검증에 최적화되어 있으며, Azure의 관리형 서비스를 활용하여 운영 부담을 최소화하면서도 실제 운영환경과 유사한 아키텍처 패턴을 적용했습니다.