kt-event-marketing-fe/deployment/k8s/deploy-k8s-guide.md

# KT 이벤트 마케팅 프론트엔드 Kubernetes 배포 가이드

## 1. 배포 정보

### 실행 정보
- **시스템명**: kt-event-marketing-frontend
- **서비스명**: kt-event-marketing-frontend
- **ACR명**: acrdigitalgarage01
- **k8s명**: aks-digitalgarage-01
- **네임스페이스**: kt-event-marketing
- **파드수**: 1
- **리소스(CPU)**: 256m/1024m
- **리소스(메모리)**: 256Mi/1024Mi
- **Gateway Host**: http://kt-event-marketing-api.20.214.196.128.nip.io

### 배포 URL
- **프론트엔드 접속 URL**: http://kt-event-marketing-frontend.20.214.196.128.nip.io

---

## 2. 배포 검증 결과

### ✅ 체크리스트 검증 완료

#### 객체 이름 네이밍 룰 준수
- ✅ Ingress: `kt-event-marketing-frontend`
- ✅ ConfigMap: `cm-kt-event-marketing-frontend`
- ✅ Service: `kt-event-marketing-frontend`
- ✅ Deployment: `kt-event-marketing-frontend`

#### Ingress Controller External IP 확인
```bash
kubectl get svc ingress-nginx-controller -n ingress-nginx
```
**결과**:
```
NAME                       TYPE           CLUSTER-IP    EXTERNAL-IP      PORT(S)                      AGE
ingress-nginx-controller   LoadBalancer   10.0.76.134   20.214.196.128   80:32094/TCP,443:30210/TCP   204d
```
- ✅ External IP: `20.214.196.128`
- ✅ Ingress Host: `kt-event-marketing-frontend.20.214.196.128.nip.io`

#### 포트 일치성 확인
- ✅ Ingress의 backend.service.port.number: `8080`
- ✅ Service의 port: `8080`
- ✅ Service의 targetPort: `8080`

#### 이미지명 확인
- ✅ 이미지명: `acrdigitalgarage01.azurecr.io/kt-event-marketing-frontend/kt-event-marketing-frontend:latest`

#### ConfigMap 데이터 확인
- ✅ ConfigMap 이름: `cm-kt-event-marketing-frontend`
- ✅ Key: `runtime-env.js`
- ✅ Value: 모든 백엔드 API 호스트가 `http://kt-event-marketing-api.20.214.196.128.nip.io`로 설정됨
  - USER_HOST
  - EVENT_HOST
  - CONTENT_HOST
  - AI_HOST
  - PARTICIPATION_HOST
  - DISTRIBUTION_HOST
  - ANALYTICS_HOST

---

## 3. 배포 전 사전 확인

### 3.1 Azure 로그인 상태 확인
```bash
az account show
```
**확인 사항**: 올바른 Azure 구독에 로그인되어 있는지 확인

### 3.2 AKS Credential 확인
```bash
kubectl cluster-info
```
**확인 사항**: aks-digitalgarage-01 클러스터에 연결되어 있는지 확인

AKS 자격 증명이 설정되어 있지 않다면 다음 명령 실행:
```bash
az aks get-credentials --resource-group <리소스그룹명> --name aks-digitalgarage-01
```

### 3.3 Namespace 존재 확인
```bash
kubectl get ns kt-event-marketing
```
**확인 사항**: kt-event-marketing 네임스페이스가 존재하는지 확인

네임스페이스가 없다면 생성:
```bash
kubectl create namespace kt-event-marketing
```

### 3.4 ImagePullSecret 확인
배포 전에 ACR 접근을 위한 ImagePullSecret이 네임스페이스에 존재하는지 확인:
```bash
kubectl get secret kt-event-marketing-frontend -n kt-event-marketing
```

ImagePullSecret이 없다면 생성:
```bash
kubectl create secret docker-registry kt-event-marketing-frontend \
  --docker-server=acrdigitalgarage01.azurecr.io \
  --docker-username=<ACR_USERNAME> \
  --docker-password=<ACR_PASSWORD> \
  --namespace=kt-event-marketing
```

---

## 4. 매니페스트 적용

### 4.1 모든 매니페스트 일괄 적용
```bash
kubectl apply -f deployment/k8s/
```

### 4.2 개별 매니페스트 적용 (선택 사항)
순서대로 적용하려면:
```bash
# 1. ConfigMap 적용
kubectl apply -f deployment/k8s/configmap.yaml

# 2. Service 적용
kubectl apply -f deployment/k8s/service.yaml

# 3. Deployment 적용
kubectl apply -f deployment/k8s/deployment.yaml

# 4. Ingress 적용
kubectl apply -f deployment/k8s/ingress.yaml
```

---

## 5. 배포 확인

### 5.1 ConfigMap 확인
```bash
kubectl get configmap cm-kt-event-marketing-frontend -n kt-event-marketing
```

ConfigMap 내용 상세 확인:
```bash
kubectl describe configmap cm-kt-event-marketing-frontend -n kt-event-marketing
```

### 5.2 Service 확인
```bash
kubectl get service kt-event-marketing-frontend -n kt-event-marketing
```

Service 상세 확인:
```bash
kubectl describe service kt-event-marketing-frontend -n kt-event-marketing
```

### 5.3 Deployment 확인
```bash
kubectl get deployment kt-event-marketing-frontend -n kt-event-marketing
```

Deployment 상세 확인:
```bash
kubectl describe deployment kt-event-marketing-frontend -n kt-event-marketing
```

### 5.4 Pod 상태 확인
```bash
kubectl get pods -n kt-event-marketing -l app=kt-event-marketing-frontend
```

Pod 상세 확인:
```bash
kubectl describe pod -n kt-event-marketing -l app=kt-event-marketing-frontend
```

Pod 로그 확인:
```bash
kubectl logs -n kt-event-marketing -l app=kt-event-marketing-frontend --tail=100
```

### 5.5 Ingress 확인
```bash
kubectl get ingress kt-event-marketing-frontend -n kt-event-marketing
```

Ingress 상세 확인:
```bash
kubectl describe ingress kt-event-marketing-frontend -n kt-event-marketing
```

---

## 6. 배포 검증

### 6.1 Health Check 확인
```bash
kubectl exec -n kt-event-marketing -it $(kubectl get pod -n kt-event-marketing -l app=kt-event-marketing-frontend -o jsonpath='{.items[0].metadata.name}') -- curl http://localhost:8080/health
```

### 6.2 웹 브라우저 접속 테스트
브라우저에서 다음 URL로 접속:
```
http://kt-event-marketing-frontend.20.214.196.128.nip.io
```

### 6.3 Runtime Config 확인
브라우저 개발자 도구 콘솔에서 확인:
```javascript
console.log(window.__runtime_config__);
```

모든 API 호스트가 `http://kt-event-marketing-api.20.214.196.128.nip.io`로 설정되어 있는지 확인

---

## 7. 트러블슈팅

### Pod가 Running 상태가 아닌 경우

#### ImagePullBackOff 에러
```bash
# ImagePullSecret 확인
kubectl get secret kt-event-marketing-frontend -n kt-event-marketing

# Secret이 없으면 생성
kubectl create secret docker-registry kt-event-marketing-frontend \
  --docker-server=acrdigitalgarage01.azurecr.io \
  --docker-username=<ACR_USERNAME> \
  --docker-password=<ACR_PASSWORD> \
  --namespace=kt-event-marketing
```

#### CrashLoopBackOff 에러
```bash
# Pod 로그 확인
kubectl logs -n kt-event-marketing -l app=kt-event-marketing-frontend --tail=100

# 이전 컨테이너 로그 확인
kubectl logs -n kt-event-marketing -l app=kt-event-marketing-frontend --previous
```

#### Probe Failure
```bash
# Pod 이벤트 확인
kubectl describe pod -n kt-event-marketing -l app=kt-event-marketing-frontend

# Health endpoint 직접 확인
kubectl exec -n kt-event-marketing -it $(kubectl get pod -n kt-event-marketing -l app=kt-event-marketing-frontend -o jsonpath='{.items[0].metadata.name}') -- curl http://localhost:8080/health
```

### Ingress로 접속이 안 되는 경우

#### Ingress Controller 확인
```bash
kubectl get svc ingress-nginx-controller -n ingress-nginx
```

#### Ingress 상태 확인
```bash
kubectl describe ingress kt-event-marketing-frontend -n kt-event-marketing
```

#### Service Endpoint 확인
```bash
kubectl get endpoints kt-event-marketing-frontend -n kt-event-marketing
```

### ConfigMap이 마운트되지 않는 경우
```bash
# Pod 내부 확인
kubectl exec -n kt-event-marketing -it $(kubectl get pod -n kt-event-marketing -l app=kt-event-marketing-frontend -o jsonpath='{.items[0].metadata.name}') -- ls -la /usr/share/nginx/html/runtime-env.js

# ConfigMap 마운트 확인
kubectl exec -n kt-event-marketing -it $(kubectl get pod -n kt-event-marketing -l app=kt-event-marketing-frontend -o jsonpath='{.items[0].metadata.name}') -- cat /usr/share/nginx/html/runtime-env.js
```

---

## 8. 재배포 방법

### 8.1 ConfigMap 업데이트 후 재배포
```bash
# ConfigMap 수정
kubectl edit configmap cm-kt-event-marketing-frontend -n kt-event-marketing

# Pod 재시작
kubectl rollout restart deployment kt-event-marketing-frontend -n kt-event-marketing
```

### 8.2 새 이미지 버전 배포
```bash
# 새 이미지로 업데이트
kubectl set image deployment/kt-event-marketing-frontend \
  kt-event-marketing-frontend=acrdigitalgarage01.azurecr.io/kt-event-marketing-frontend/kt-event-marketing-frontend:새버전 \
  -n kt-event-marketing

# 롤아웃 상태 확인
kubectl rollout status deployment/kt-event-marketing-frontend -n kt-event-marketing
```

### 8.3 매니페스트 파일 수정 후 재배포
```bash
# 매니페스트 적용
kubectl apply -f deployment/k8s/

# 롤아웃 상태 확인
kubectl rollout status deployment/kt-event-marketing-frontend -n kt-event-marketing
```

### 8.4 롤백
```bash
# 이전 버전으로 롤백
kubectl rollout undo deployment/kt-event-marketing-frontend -n kt-event-marketing

# 특정 리비전으로 롤백
kubectl rollout undo deployment/kt-event-marketing-frontend --to-revision=<리비전번호> -n kt-event-marketing

# 롤아웃 히스토리 확인
kubectl rollout history deployment/kt-event-marketing-frontend -n kt-event-marketing
```

---

## 9. 삭제 방법

### 9.1 전체 삭제
```bash
kubectl delete -f deployment/k8s/
```

### 9.2 개별 리소스 삭제
```bash
# Ingress 삭제
kubectl delete ingress kt-event-marketing-frontend -n kt-event-marketing

# Deployment 삭제
kubectl delete deployment kt-event-marketing-frontend -n kt-event-marketing

# Service 삭제
kubectl delete service kt-event-marketing-frontend -n kt-event-marketing

# ConfigMap 삭제
kubectl delete configmap cm-kt-event-marketing-frontend -n kt-event-marketing
```

---

## 10. 모니터링

### 10.1 실시간 Pod 로그 확인
```bash
kubectl logs -n kt-event-marketing -l app=kt-event-marketing-frontend -f
```

### 10.2 리소스 사용량 확인
```bash
kubectl top pod -n kt-event-marketing -l app=kt-event-marketing-frontend
```

### 10.3 이벤트 모니터링
```bash
kubectl get events -n kt-event-marketing --sort-by='.lastTimestamp'
```

---

## 부록: 생성된 매니페스트 파일

### A. ConfigMap (configmap.yaml)
- 파일 위치: `deployment/k8s/configmap.yaml`
- 용도: runtime-env.js 설정 주입
- 마운트 경로: `/usr/share/nginx/html/runtime-env.js`

### B. Service (service.yaml)
- 파일 위치: `deployment/k8s/service.yaml`
- 타입: ClusterIP
- 포트: 8080

### C. Deployment (deployment.yaml)
- 파일 위치: `deployment/k8s/deployment.yaml`
- 레플리카: 1
- 이미지: `acrdigitalgarage01.azurecr.io/kt-event-marketing-frontend/kt-event-marketing-frontend:latest`
- 리소스 제한: CPU 256m-1024m, Memory 256Mi-1024Mi

### D. Ingress (ingress.yaml)
- 파일 위치: `deployment/k8s/ingress.yaml`
- 호스트: `kt-event-marketing-frontend.20.214.196.128.nip.io`
- 백엔드: kt-event-marketing-frontend:8080

---

## 문의사항
배포 중 문제가 발생하면 위의 트러블슈팅 섹션을 참고하거나 관리자에게 문의하세요.