kt-event-marketing/deployment/uiux/README.md

KT 이벤트 마케팅 프로토타입 배포 가이드

UI/UX 프로토타입을 Docker 컨테이너로 빌드하고 Kubernetes 클러스터에 배포하는 가이드입니다.

📋 목차

1. 사전 요구사항
2. 이미지 빌드
3. 로컬 테스트
4. Kubernetes 배포
5. 접속 및 확인
6. 문제 해결

---

🔧 사전 요구사항

필수 도구

• Docker (버전 20.10 이상)
• kubectl (버전 1.24 이상)
• Kubernetes 클러스터 (접근 권한 필요)

환경 변수 설정 (선택사항)

# Docker 레지스트리 설정
export DOCKER_REGISTRY=acrdigitalgarage01.azurecr.io  # Azure Container Registry
export IMAGE_TAG=v1.0.0                                # 기본값: latest

# Kubernetes 네임스페이스 설정
export KUBE_NAMESPACE=kt-event-marketing              # 기본값: kt-event-marketing

---

🔨 이미지 빌드

1. 빌드 스크립트 실행

프로젝트 루트에서 다음 명령어를 실행합니다:

./deployment/uiux/build.sh

2. 빌드 프로세스

스크립트는 다음 단계를 수행합니다:

1. Docker 이미지 빌드
2. 레지스트리 푸시 여부 확인
3. (선택시) 이미지를 레지스트리에 푸시

3. 수동 빌드 (선택사항)

스크립트를 사용하지 않고 수동으로 빌드할 수도 있습니다:

# 이미지 빌드
docker build -f deployment/uiux/Dockerfile \
  -t acrdigitalgarage01.azurecr.io/kt-event-prototype:latest .

# 레지스트리에 푸시
docker push acrdigitalgarage01.azurecr.io/kt-event-prototype:latest

---

🧪 로컬 테스트

Kubernetes에 배포하기 전에 로컬에서 테스트할 수 있습니다:

# 컨테이너 실행
docker run -d -p 8080:80 --name prototype \
  acrdigitalgarage01.azurecr.io/kt-event-prototype:latest

# 브라우저에서 접속
# http://localhost:8080

# 컨테이너 중지 및 제거
docker stop prototype
docker rm prototype

헬스체크 확인

curl http://localhost:8080/health
# 출력: OK

---

☸️ Kubernetes 배포

1. 배포 스크립트 실행

./deployment/uiux/deploy.sh

2. 배포 옵션 선택

스크립트 실행 시 다음 옵션을 선택할 수 있습니다:

• 1) 전체 배포: Deployment + Service + Ingress 모두 배포
• 2) 업데이트: Deployment 업데이트 (이미지 변경 시)
• 3) 삭제: 모든 리소스 삭제

3. 수동 배포 (선택사항)

# 모든 리소스 배포
kubectl apply -f deployment/uiux/k8s/deployment.yaml
kubectl apply -f deployment/uiux/k8s/service.yaml
kubectl apply -f deployment/uiux/k8s/ingress.yaml

# 배포 상태 확인
kubectl rollout status deployment/kt-event-prototype

4. 이미지 업데이트

새 이미지로 업데이트하려면:

# 새 이미지로 태그 변경
kubectl set image deployment/kt-event-prototype \
  nginx=acrdigitalgarage01.azurecr.io/kt-event-prototype:v1.0.1 \
  -n kt-event-marketing

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

# 롤백 (필요시)
kubectl rollout undo deployment/kt-event-prototype -n kt-event-marketing

---

🌐 접속 및 확인

1. Pod 상태 확인

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

정상 상태:

NAME                                   READY   STATUS    RESTARTS   AGE
kt-event-prototype-xxxxxxxxxx-xxxxx   1/1     Running   0          1m

2. Service 확인

kubectl get svc kt-event-prototype -n kt-event-marketing

3. Ingress 확인

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

Ingress 호스트 주소: prototype.kt-event.kubepia.com

4. 브라우저에서 접속

http://prototype.kt-event.kubepia.com

참고: 도메인이 외부 DNS에 등록되어 있지 않은 경우, /etc/hosts (또는 Windows: C:\Windows\System32\drivers\etc\hosts) 파일에 다음을 추가하여 로컬 테스트 가능:

<INGRESS_CONTROLLER_IP> prototype.kt-event.kubepia.com

Ingress Controller IP 확인:

kubectl get svc -n ingress-nginx

6. 프로토타입 화면 목록

접속 후 다음 화면들을 확인할 수 있습니다:

• 01-로그인.html
• 02-회원가입.html
• 03-프로필.html
• 04-로그아웃확인.html
• 05-대시보드.html
• 06-이벤트목록.html
• 07-이벤트목적선택.html
• 08-AI이벤트추천.html
• 09-콘텐츠미리보기.html
• 10-콘텐츠편집.html
• 11-이벤트게시.html
• 12-내이벤트.html
• 13-이벤트상세.html
• 14-이벤트수정.html
• 15-이벤트삭제확인.html
• 16-통계대시보드.html
• 17-예산관리.html
• 18-공유하기.html
• 19-알림센터.html
• 20-도움말.html

---

🔍 문제 해결

Pod가 시작하지 않을 때

# Pod 상세 정보 확인
kubectl describe pod -l app=kt-event-prototype -n kt-event-marketing

# Pod 로그 확인
kubectl logs -l app=kt-event-prototype -n kt-event-marketing

# 이벤트 확인
kubectl get events -n kt-event-marketing --sort-by='.lastTimestamp'

일반적인 문제

1. ImagePullBackOff 에러

• 원인: 이미지를 레지스트리에서 가져올 수 없음
• 해결:

  # 이미지 이름 확인
  kubectl get deployment kt-event-prototype -n kt-event-marketing \
    -o jsonpath='{.spec.template.spec.containers[0].image}'
  
  # 수동으로 이미지 pull 테스트
  docker pull acrdigitalgarage01.azurecr.io/kt-event-prototype:latest
  

2. CrashLoopBackOff 에러

• 원인: 컨테이너가 시작 후 계속 종료됨
• 해결:

  # 로그 확인
  kubectl logs -l app=kt-event-prototype -n kt-event-marketing --previous
  
  # 컨테이너 내부 확인
  kubectl exec -it <pod-name> -n kt-event-marketing -- sh
  

3. Ingress 접속 안됨

• 원인: Ingress Controller 미설치 또는 DNS 미설정
• 해결:

  # Ingress Controller 확인
  kubectl get pods -n ingress-nginx
  
  # Ingress 상세 확인
  kubectl describe ingress kt-event-prototype -n kt-event-marketing
  

로그 확인 명령어

# 실시간 로그 확인
kubectl logs -f -l app=kt-event-prototype -n kt-event-marketing

# 최근 100줄 로그
kubectl logs --tail=100 -l app=kt-event-prototype -n kt-event-marketing

# 모든 Pod의 로그
kubectl logs -l app=kt-event-prototype -n kt-event-marketing --all-containers=true

# 이전 컨테이너 로그 (CrashLoopBackOff 시)
kubectl logs -l app=kt-event-prototype -n kt-event-marketing --previous

리소스 정리

# 모든 리소스 삭제
kubectl delete -f deployment/uiux/k8s/ -n kt-event-marketing

# 또는 개별 삭제
kubectl delete ingress kt-event-prototype -n kt-event-marketing
kubectl delete service kt-event-prototype -n kt-event-marketing
kubectl delete deployment kt-event-prototype -n kt-event-marketing

---

📊 리소스 사양

Deployment

• Replicas: 2개 (고가용성)
• Container Port: 80
• Resources:
  • CPU: 100m (request), 200m (limit)
  • Memory: 128Mi (request), 256Mi (limit)

Service

• Type: ClusterIP
• Port: 80

Ingress

• Host: prototype.kt-event.local (변경 필요)
• Path: / (모든 경로)
• Backend: kt-event-prototype:80

---

🔐 보안 설정

• runAsNonRoot: true (root 사용자로 실행 안함)
• readOnlyRootFilesystem: false (nginx 로그 작성 허용)
• allowPrivilegeEscalation: false
• Capabilities: NET_BIND_SERVICE만 허용

---

📝 참고 사항

1. 도메인: 현재 prototype.kt-event.kubepia.com으로 설정되어 있습니다. 변경이 필요한 경우 k8s/ingress.yaml에서 수정하세요.
2. 네임스페이스: kt-event-marketing 네임스페이스를 사용합니다. 환경변수 KUBE_NAMESPACE로 변경 가능합니다.
3. 레지스트리: Azure Container Registry(acrdigitalgarage01.azurecr.io)를 사용합니다.
4. 리소스 제한: 프로덕션 환경에서는 리소스 요청/제한을 조정하세요.
5. TLS: HTTPS 사용 시 ingress.yaml에서 TLS 섹션을 활성화하세요.
6. 모니터링: Prometheus/Grafana를 통한 모니터링 권장합니다.
7. nginx 설정: nginx 설정은 Docker 이미지에 포함되어 있습니다. 변경이 필요한 경우 nginx.conf를 수정하고 이미지를 재빌드하세요.

---

🤝 지원

문제가 발생하면 다음을 확인하세요:

1. Pod 로그
2. Ingress Controller 로그
3. Kubernetes 이벤트

추가 지원이 필요하면 개발팀에 문의하세요.