hgzero/ai-python/DEPLOYMENT.md

# AI Service (Python) - AKS 배포 가이드

## 📋 사전 준비

### 1. Azure Container Registry (ACR) 접근 권한
```bash
# ACR 로그인
az acr login --name acrdigitalgarage02
```

### 2. Kubernetes 클러스터 접근
```bash
# AKS 자격 증명 가져오기
az aks get-credentials --resource-group <리소스그룹> --name <클러스터명>

# 네임스페이스 확인
kubectl get namespace hgzero
```

## 🐳 1단계: Docker 이미지 빌드 및 푸시

### 이미지 빌드
```bash
cd ai-python

# 이미지 빌드
docker build -t acrdigitalgarage02.azurecr.io/hgzero/ai-service:latest .

# 특정 버전 태그도 함께 생성 (권장)
docker tag acrdigitalgarage02.azurecr.io/hgzero/ai-service:latest \
  acrdigitalgarage02.azurecr.io/hgzero/ai-service:v1.0.0
```

### ACR에 푸시
```bash
# latest 태그 푸시
docker push acrdigitalgarage02.azurecr.io/hgzero/ai-service:latest

# 버전 태그 푸시
docker push acrdigitalgarage02.azurecr.io/hgzero/ai-service:v1.0.0
```

### 로컬 테스트 (선택)
```bash
# 이미지 실행 테스트
docker run -p 8087:8087 \
  -e CLAUDE_API_KEY="your-api-key" \
  -e REDIS_HOST="20.249.177.114" \
  -e REDIS_PASSWORD="Hi5Jessica!" \
  acrdigitalgarage02.azurecr.io/hgzero/ai-service:latest

# 헬스 체크
curl http://localhost:8087/health
```

## 🔐 2단계: Kubernetes Secret 생성

### Claude API Key Secret 생성
```bash
# Claude API Key를 base64로 인코딩
echo -n "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" | base64

# Secret 생성
kubectl create secret generic ai-secret \
  --from-literal=claude-api-key="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" \
  -n hgzero
```

### Event Hub Secret 생성 (기존에 없는 경우)
```bash
# Event Hub Connection String (AI Listen Policy)
kubectl create secret generic azure-secret \
  --from-literal=eventhub-ai-connection-string="Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;SharedAccessKeyName=ai-listen-policy;SharedAccessKey=wqcbVIXlOMyn/C562lx6DD75AyjHQ87xo+AEhJ7js9Q=" \
  -n hgzero --dry-run=client -o yaml | kubectl apply -f -
```

### Redis Secret 확인/생성
```bash
# 기존 Redis Secret 확인
kubectl get secret redis-secret -n hgzero

# 없으면 생성
kubectl create secret generic redis-secret \
  --from-literal=password="Hi5Jessica!" \
  -n hgzero
```

### ConfigMap 확인
```bash
# Redis ConfigMap 확인
kubectl get configmap redis-config -n hgzero

# 없으면 생성
kubectl create configmap redis-config \
  --from-literal=host="20.249.177.114" \
  --from-literal=port="6379" \
  -n hgzero
```

## 🚀 3단계: AI 서비스 배포

### 배포 실행
```bash
# 배포 매니페스트 적용
kubectl apply -f deploy/k8s/backend/ai-service.yaml

# 배포 상태 확인
kubectl get deployment ai-service -n hgzero
kubectl get pods -n hgzero -l app=ai-service
```

### 로그 확인
```bash
# Pod 이름 가져오기
POD_NAME=$(kubectl get pods -n hgzero -l app=ai-service -o jsonpath='{.items[0].metadata.name}')

# 실시간 로그 확인
kubectl logs -f $POD_NAME -n hgzero

# Event Hub 연결 로그 확인
kubectl logs $POD_NAME -n hgzero | grep "Event Hub"
```

## 🌐 4단계: Ingress 업데이트

### Ingress 적용
```bash
# Ingress 설정 적용
kubectl apply -f .github/kustomize/base/common/ingress.yaml

# Ingress 확인
kubectl get ingress -n hgzero
kubectl describe ingress hgzero -n hgzero
```

### 접속 테스트
```bash
# 서비스 URL
AI_SERVICE_URL="http://hgzero-api.20.214.196.128.nip.io"

# 헬스 체크
curl $AI_SERVICE_URL/api/ai/suggestions/test

# Swagger UI
echo "Swagger UI: $AI_SERVICE_URL/swagger-ui.html"
```

## ✅ 5단계: 배포 검증

### Pod 상태 확인
```bash
# Pod 상태
kubectl get pods -n hgzero -l app=ai-service

# Pod 상세 정보
kubectl describe pod -n hgzero -l app=ai-service

# Pod 리소스 사용량
kubectl top pod -n hgzero -l app=ai-service
```

### 서비스 확인
```bash
# Service 확인
kubectl get svc ai-service -n hgzero

# Service 상세 정보
kubectl describe svc ai-service -n hgzero
```

### 엔드포인트 테스트
```bash
# 내부 테스트 (Pod에서)
kubectl exec -it $POD_NAME -n hgzero -- curl http://localhost:8087/health

# 외부 테스트 (Ingress 통해)
curl http://hgzero-api.20.214.196.128.nip.io/api/ai/suggestions/test

# SSE 스트리밍 테스트
curl -N http://hgzero-api.20.214.196.128.nip.io/api/ai/suggestions/meetings/test-meeting/stream
```

## 🔄 업데이트 배포

### 새 버전 배포
```bash
# 1. 새 이미지 빌드 및 푸시
docker build -t acrdigitalgarage02.azurecr.io/hgzero/ai-service:v1.0.1 .
docker push acrdigitalgarage02.azurecr.io/hgzero/ai-service:v1.0.1

# 2. Deployment 이미지 업데이트
kubectl set image deployment/ai-service \
  ai-service=acrdigitalgarage02.azurecr.io/hgzero/ai-service:v1.0.1 \
  -n hgzero

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

# 4. 롤아웃 히스토리
kubectl rollout history deployment/ai-service -n hgzero
```

### 롤백 (문제 발생 시)
```bash
# 이전 버전으로 롤백
kubectl rollout undo deployment/ai-service -n hgzero

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

## 🐛 트러블슈팅

### Pod가 Running 상태가 아닌 경우
```bash
# Pod 상태 확인
kubectl get pods -n hgzero -l app=ai-service

# Pod 이벤트 확인
kubectl describe pod -n hgzero -l app=ai-service

# 로그 확인
kubectl logs -n hgzero -l app=ai-service
```

### ImagePullBackOff 에러
```bash
# ACR 접근 권한 확인
kubectl get secret -n hgzero

# ACR Pull Secret 생성 (필요시)
kubectl create secret docker-registry acr-secret \
  --docker-server=acrdigitalgarage02.azurecr.io \
  --docker-username=<ACR_USERNAME> \
  --docker-password=<ACR_PASSWORD> \
  -n hgzero
```

### CrashLoopBackOff 에러
```bash
# 로그 확인
kubectl logs -n hgzero -l app=ai-service --previous

# 환경 변수 확인
kubectl exec -it $POD_NAME -n hgzero -- env | grep -E "CLAUDE|REDIS|EVENTHUB"
```

### Redis 연결 실패
```bash
# Redis 접속 테스트 (Pod에서)
kubectl exec -it $POD_NAME -n hgzero -- \
  python -c "import redis; r=redis.Redis(host='20.249.177.114', port=6379, password='Hi5Jessica!', db=4); print(r.ping())"
```

### Event Hub 연결 실패
```bash
# Event Hub 연결 문자열 확인
kubectl get secret azure-secret -n hgzero -o jsonpath='{.data.eventhub-ai-connection-string}' | base64 -d

# 로그에서 Event Hub 오류 확인
kubectl logs $POD_NAME -n hgzero | grep -i "eventhub\|error"
```

## 📊 모니터링

### 실시간 로그 모니터링
```bash
# 실시간 로그
kubectl logs -f -n hgzero -l app=ai-service

# 특정 키워드 필터링
kubectl logs -f -n hgzero -l app=ai-service | grep -E "SSE|Claude|AI"
```

### 리소스 사용량
```bash
# CPU/메모리 사용량
kubectl top pod -n hgzero -l app=ai-service

# 상세 리소스 정보
kubectl describe pod -n hgzero -l app=ai-service | grep -A 5 "Resources"
```

## 🗑️ 삭제

### AI 서비스 삭제
```bash
# Deployment와 Service 삭제
kubectl delete -f deploy/k8s/backend/ai-service.yaml

# Secret 삭제
kubectl delete secret ai-secret -n hgzero

# ConfigMap 유지 (다른 서비스에서 사용 중)
# kubectl delete configmap redis-config -n hgzero
```

## 📝 주의사항

1. **Secret 관리**
   - Claude API Key는 민감 정보이므로 Git에 커밋하지 마세요
   - 프로덕션 환경에서는 Azure Key Vault 사용 권장

2. **리소스 제한**
   - 초기 설정: CPU 250m-1000m, Memory 512Mi-1024Mi
   - 트래픽에 따라 조정 필요

3. **Event Hub**
   - AI Listen Policy 사용 (Listen 권한만)
   - EntityPath는 연결 문자열에서 제거

4. **Redis**
   - DB 4번 사용 (다른 서비스와 분리)
   - TTL 5분 설정 (슬라이딩 윈도우)

5. **Ingress 경로**
   - `/api/ai/suggestions`가 `/api/ai`보다 먼저 정의되어야 함
   - 더 구체적인 경로를 위에 배치