hgzero/deploy/k8s/backend

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 설치

   # macOS
   brew install azure-cli
   
   # Windows
   # Download from https://aka.ms/installazurecliwindows
   
   # Linux
   curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
   

2. kubectl 설치

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

   az login
   

4. ACR 로그인

   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 클러스터 접근 설정

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

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

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

kubectl apply -f namespace.yaml

3단계: ConfigMap 생성

kubectl apply -f configmap.yaml

4단계: Secret 생성

옵션 A: 대화형 스크립트 사용 (권장)

./create-secrets.sh

옵션 B: 직접 생성

# 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: 자동 배포 스크립트 사용 (권장)

./deploy.sh

옵션 B: 수동 배포

# 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단계: 배포 상태 확인

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

# 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

# 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 내부 접속

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

배포 해제

전체 서비스 삭제

./undeploy.sh

개별 서비스 삭제

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

Secret 및 ConfigMap 삭제

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

네임스페이스 삭제

kubectl delete namespace hgzero

트러블슈팅

Pod가 시작되지 않는 경우

# 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 오류

# 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 관련 오류

# 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

네트워크 연결 문제

# 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

리소스 부족 문제

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

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

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

업데이트 및 롤링 배포

이미지 업데이트

# 새 이미지 태그로 업데이트
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

롤백

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

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

모니터링

Kubernetes Dashboard

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

리소스 모니터링

# 실시간 리소스 사용량 모니터링
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 설정

   kubectl autoscale deployment user-service \
     --cpu-percent=70 \
     --min=1 \
     --max=5 \
     -n hgzero
   

2. 리소스 조정

   • 실제 사용량에 따라 requests/limits를 조정하세요
   • HPA(Horizontal Pod Autoscaler) 설정을 고려하세요

참고 자료

• Azure Kubernetes Service 문서
• Kubernetes 공식 문서
• kubectl 치트시트

지원 및 문의

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

# 진단 정보 수집
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