hgzero/deploy/k8s/backend/README.md

# HGZero 백엔드 서비스 Kubernetes 배포 가이드

## 개요

이 가이드는 HGZero 백엔드 서비스(User, Meeting, Notification)를 Azure Kubernetes Service(AKS)에 배포하는 방법을 설명합니다.

## 배포 환경

- **ACR(Azure Container Registry)**: acrdigitalgarage02
- **AKS(Azure Kubernetes Service)**: aks-digitalgarage-02
- **네임스페이스**: hgzero
- **리소스 그룹**: rg-digitalgarage-02

## 서비스 구성

### 1. User Service
- **포트**: 8080
- **이미지**: acrdigitalgarage02.azurecr.io/hgzero/user-service:latest
- **기능**: 사용자 인증 및 관리, LDAP 연동

### 2. Meeting Service
- **포트**: 8081 (HTTP), 8082 (WebSocket)
- **이미지**: acrdigitalgarage02.azurecr.io/hgzero/meeting-service:latest
- **기능**: 회의 관리, WebSocket 통신

### 3. Notification Service
- **포트**: 8082
- **이미지**: acrdigitalgarage02.azurecr.io/hgzero/notification-service:latest
- **기능**: 알림 전송, 이메일 발송

## 리소스 할당

각 서비스는 다음과 같은 리소스를 사용합니다:

- **Requests**:
  - CPU: 256m
  - Memory: 256Mi
- **Limits**:
  - CPU: 1024m
  - Memory: 1024Mi
- **Replicas**: 1 (각 서비스)

## 사전 요구사항

1. **Azure CLI 설치**
   ```bash
   # macOS
   brew install azure-cli

   # Windows
   # Download from https://aka.ms/installazurecliwindows

   # Linux
   curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
   ```

2. **kubectl 설치**
   ```bash
   # macOS
   brew install kubectl

   # Windows
   # Download from https://kubernetes.io/docs/tasks/tools/install-kubectl-windows/

   # Linux
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
   sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
   ```

3. **Azure 로그인**
   ```bash
   az login
   ```

4. **ACR 로그인**
   ```bash
   az acr login --name acrdigitalgarage02
   ```

## 배포 파일 구조

```
deploy/k8s/backend/
├── namespace.yaml              # 네임스페이스 정의
├── configmap.yaml              # ConfigMap (Redis, Mail 설정)
├── secret-template.yaml        # Secret 템플릿 (민감 정보)
├── user-service.yaml           # User Service 배포 매니페스트
├── meeting-service.yaml        # Meeting Service 배포 매니페스트
├── notification-service.yaml   # Notification Service 배포 매니페스트
├── deploy.sh                   # 배포 스크립트
├── undeploy.sh                 # 배포 해제 스크립트
├── create-secrets.sh           # Secret 생성 스크립트
└── README.md                   # 이 문서
```

## 배포 절차

### 1단계: AKS 클러스터 접근 설정

```bash
# AKS credentials 가져오기
az aks get-credentials \
  --resource-group rg-digitalgarage-02 \
  --name aks-digitalgarage-02 \
  --overwrite-existing

# 클러스터 연결 확인
kubectl cluster-info
```

### 2단계: 네임스페이스 생성

```bash
kubectl apply -f namespace.yaml
```

### 3단계: ConfigMap 생성

```bash
kubectl apply -f configmap.yaml
```

### 4단계: Secret 생성

옵션 A: 대화형 스크립트 사용 (권장)
```bash
./create-secrets.sh
```

옵션 B: 직접 생성
```bash
# Database Secret
kubectl create secret generic db-secret \
  --from-literal=host=<DB_HOST> \
  --from-literal=username=<DB_USERNAME> \
  --from-literal=password=<DB_PASSWORD> \
  --namespace=hgzero

# Azure Secret
kubectl create secret generic azure-secret \
  --from-literal=eventhub-connection-string=<EVENTHUB_CONN> \
  --from-literal=blob-connection-string=<BLOB_CONN> \
  --namespace=hgzero

# Mail Secret
kubectl create secret generic mail-secret \
  --from-literal=username=<MAIL_USERNAME> \
  --from-literal=password=<MAIL_PASSWORD> \
  --namespace=hgzero
```

### 5단계: 서비스 배포

옵션 A: 자동 배포 스크립트 사용 (권장)
```bash
./deploy.sh
```

옵션 B: 수동 배포
```bash
# ACR 연동 설정
az aks update \
  -n aks-digitalgarage-02 \
  -g rg-digitalgarage-02 \
  --attach-acr acrdigitalgarage02

# 서비스 배포
kubectl apply -f user-service.yaml
kubectl apply -f notification-service.yaml
kubectl apply -f meeting-service.yaml
```

### 6단계: 배포 상태 확인

```bash
# Deployment 상태 확인
kubectl get deployments -n hgzero

# Pod 상태 확인
kubectl get pods -n hgzero

# Service 확인
kubectl get services -n hgzero

# 상세 정보 확인
kubectl describe deployment user-service -n hgzero
```

## 배포 확인 및 테스트

### Pod 로그 확인

```bash
# User Service 로그
kubectl logs -f deployment/user-service -n hgzero

# Meeting Service 로그
kubectl logs -f deployment/meeting-service -n hgzero

# Notification Service 로그
kubectl logs -f deployment/notification-service -n hgzero
```

### Health Check

```bash
# User Service health check
kubectl port-forward svc/user-service 8080:8080 -n hgzero
curl http://localhost:8080/actuator/health

# Meeting Service health check
kubectl port-forward svc/meeting-service 8081:8081 -n hgzero
curl http://localhost:8081/actuator/health

# Notification Service health check
kubectl port-forward svc/notification-service 8082:8082 -n hgzero
curl http://localhost:8082/actuator/health
```

### Pod 내부 접속

```bash
# Pod 내부로 접속하여 디버깅
kubectl exec -it deployment/user-service -n hgzero -- /bin/sh
```

## 배포 해제

### 전체 서비스 삭제

```bash
./undeploy.sh
```

### 개별 서비스 삭제

```bash
kubectl delete -f user-service.yaml
kubectl delete -f meeting-service.yaml
kubectl delete -f notification-service.yaml
```

### Secret 및 ConfigMap 삭제

```bash
kubectl delete configmap redis-config mail-config -n hgzero
kubectl delete secret db-secret azure-secret mail-secret -n hgzero
```

### 네임스페이스 삭제

```bash
kubectl delete namespace hgzero
```

## 트러블슈팅

### Pod가 시작되지 않는 경우

```bash
# Pod 상태 확인
kubectl get pods -n hgzero

# Pod 상세 정보 확인
kubectl describe pod <pod-name> -n hgzero

# Pod 로그 확인
kubectl logs <pod-name> -n hgzero

# 이전 컨테이너 로그 확인 (재시작된 경우)
kubectl logs <pod-name> -n hgzero --previous
```

### 이미지 Pull 오류

```bash
# ACR 연동 상태 확인
az aks show -n aks-digitalgarage-02 -g rg-digitalgarage-02 --query "servicePrincipalProfile"

# ACR 재연동
az aks update -n aks-digitalgarage-02 -g rg-digitalgarage-02 --attach-acr acrdigitalgarage02

# ImagePullSecret 확인
kubectl get serviceaccount default -n hgzero -o yaml
```

### Secret 관련 오류

```bash
# Secret 존재 확인
kubectl get secrets -n hgzero

# Secret 내용 확인
kubectl get secret db-secret -n hgzero -o yaml

# Secret 재생성
kubectl delete secret db-secret -n hgzero
./create-secrets.sh
```

### 네트워크 연결 문제

```bash
# Service Endpoint 확인
kubectl get endpoints -n hgzero

# DNS 확인
kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup user-service.hgzero.svc.cluster.local

# 네트워크 정책 확인
kubectl get networkpolicies -n hgzero
```

### 리소스 부족 문제

```bash
# 노드 리소스 사용량 확인
kubectl top nodes

# Pod 리소스 사용량 확인
kubectl top pods -n hgzero

# 리소스 제한 조정 (필요 시)
kubectl edit deployment user-service -n hgzero
```

## 업데이트 및 롤링 배포

### 이미지 업데이트

```bash
# 새 이미지 태그로 업데이트
kubectl set image deployment/user-service \
  user-service=acrdigitalgarage02.azurecr.io/hgzero/user-service:v2.0.0 \
  -n hgzero

# 롤아웃 상태 확인
kubectl rollout status deployment/user-service -n hgzero

# 롤아웃 히스토리 확인
kubectl rollout history deployment/user-service -n hgzero
```

### 롤백

```bash
# 이전 버전으로 롤백
kubectl rollout undo deployment/user-service -n hgzero

# 특정 revision으로 롤백
kubectl rollout undo deployment/user-service --to-revision=2 -n hgzero
```

## 모니터링

### Kubernetes Dashboard

```bash
# Dashboard 접근
az aks browse -n aks-digitalgarage-02 -g rg-digitalgarage-02
```

### 리소스 모니터링

```bash
# 실시간 리소스 사용량 모니터링
watch kubectl top pods -n hgzero

# 이벤트 모니터링
kubectl get events -n hgzero --sort-by='.lastTimestamp'
```

## 보안 권장사항

1. **Secret 관리**
   - Secret은 절대 Git에 커밋하지 마세요
   - Azure Key Vault 통합을 고려하세요
   - Secret rotation 정책을 수립하세요

2. **네트워크 보안**
   - Network Policy를 활용하여 Pod 간 통신을 제한하세요
   - Service Mesh 도입을 고려하세요

3. **이미지 보안**
   - 정기적으로 이미지 스캔을 수행하세요
   - 최소 권한 원칙을 적용하세요

## 성능 최적화

1. **Auto Scaling 설정**
   ```bash
   kubectl autoscale deployment user-service \
     --cpu-percent=70 \
     --min=1 \
     --max=5 \
     -n hgzero
   ```

2. **리소스 조정**
   - 실제 사용량에 따라 requests/limits를 조정하세요
   - HPA(Horizontal Pod Autoscaler) 설정을 고려하세요

## 참고 자료

- [Azure Kubernetes Service 문서](https://docs.microsoft.com/azure/aks/)
- [Kubernetes 공식 문서](https://kubernetes.io/docs/)
- [kubectl 치트시트](https://kubernetes.io/docs/reference/kubectl/cheatsheet/)

## 지원 및 문의

문제 발생 시 다음 정보를 수집하여 보고해주세요:

```bash
# 진단 정보 수집
kubectl get all -n hgzero > hgzero-resources.txt
kubectl describe pods -n hgzero > hgzero-pods-detail.txt
kubectl logs deployment/user-service -n hgzero > user-service.log
kubectl logs deployment/meeting-service -n hgzero > meeting-service.log
kubectl logs deployment/notification-service -n hgzero > notification-service.log
```