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 확인

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 로그인 상태 확인

az account show

확인 사항: 올바른 Azure 구독에 로그인되어 있는지 확인

3.2 AKS Credential 확인

kubectl cluster-info

확인 사항: aks-digitalgarage-01 클러스터에 연결되어 있는지 확인

AKS 자격 증명이 설정되어 있지 않다면 다음 명령 실행:

az aks get-credentials --resource-group <리소스그룹명> --name aks-digitalgarage-01

3.3 Namespace 존재 확인

kubectl get ns kt-event-marketing

확인 사항: kt-event-marketing 네임스페이스가 존재하는지 확인

네임스페이스가 없다면 생성:

kubectl create namespace kt-event-marketing

3.4 ImagePullSecret 확인

배포 전에 ACR 접근을 위한 ImagePullSecret이 네임스페이스에 존재하는지 확인:

kubectl get secret kt-event-marketing-frontend -n kt-event-marketing

ImagePullSecret이 없다면 생성:

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 모든 매니페스트 일괄 적용

kubectl apply -f deployment/k8s/

4.2 개별 매니페스트 적용 (선택 사항)

순서대로 적용하려면:

# 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 확인

kubectl get configmap cm-kt-event-marketing-frontend -n kt-event-marketing

ConfigMap 내용 상세 확인:

kubectl describe configmap cm-kt-event-marketing-frontend -n kt-event-marketing

5.2 Service 확인

kubectl get service kt-event-marketing-frontend -n kt-event-marketing

Service 상세 확인:

kubectl describe service kt-event-marketing-frontend -n kt-event-marketing

5.3 Deployment 확인

kubectl get deployment kt-event-marketing-frontend -n kt-event-marketing

Deployment 상세 확인:

kubectl describe deployment kt-event-marketing-frontend -n kt-event-marketing

5.4 Pod 상태 확인

kubectl get pods -n kt-event-marketing -l app=kt-event-marketing-frontend

Pod 상세 확인:

kubectl describe pod -n kt-event-marketing -l app=kt-event-marketing-frontend

Pod 로그 확인:

kubectl logs -n kt-event-marketing -l app=kt-event-marketing-frontend --tail=100

5.5 Ingress 확인

kubectl get ingress kt-event-marketing-frontend -n kt-event-marketing

Ingress 상세 확인:

kubectl describe ingress kt-event-marketing-frontend -n kt-event-marketing

---

6. 배포 검증

6.1 Health Check 확인

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 확인

브라우저 개발자 도구 콘솔에서 확인:

console.log(window.__runtime_config__);

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

---

7. 트러블슈팅

Pod가 Running 상태가 아닌 경우

ImagePullBackOff 에러

# 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 에러

# 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

# 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 확인

kubectl get svc ingress-nginx-controller -n ingress-nginx

Ingress 상태 확인

kubectl describe ingress kt-event-marketing-frontend -n kt-event-marketing

Service Endpoint 확인

kubectl get endpoints kt-event-marketing-frontend -n kt-event-marketing

ConfigMap이 마운트되지 않는 경우

# 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 업데이트 후 재배포

# 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 새 이미지 버전 배포

# 새 이미지로 업데이트
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 매니페스트 파일 수정 후 재배포

# 매니페스트 적용
kubectl apply -f deployment/k8s/

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

8.4 롤백

# 이전 버전으로 롤백
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 전체 삭제

kubectl delete -f deployment/k8s/

9.2 개별 리소스 삭제

# 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 로그 확인

kubectl logs -n kt-event-marketing -l app=kt-event-marketing-frontend -f

10.2 리소스 사용량 확인

kubectl top pod -n kt-event-marketing -l app=kt-event-marketing-frontend

10.3 이벤트 모니터링

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

---

문의사항

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