From c9d24ce1af67ae2dc34a0271b87553f6344c14b9 Mon Sep 17 00:00:00 2001 From: Minseo-Jo Date: Tue, 28 Oct 2025 17:08:28 +0900 Subject: [PATCH] =?UTF-8?q?feat:=20AI=20=EC=84=9C=EB=B9=84=EC=8A=A4=20AKS?= =?UTF-8?q?=20=EB=B0=B0=ED=8F=AC=20=EC=A4=80=EB=B9=84=20=EB=B0=8F=20API=20?= =?UTF-8?q?=EA=B2=BD=EB=A1=9C=20=EC=88=98=EC=A0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## API 경로 변경 - /api/v1/ai → /api/ai 로 경로 단순화 - 최종 엔드포인트: /api/ai/suggestions/meetings/{meetingId}/stream ## Docker 컨테이너화 - Dockerfile 작성 (Python 3.11 slim 기반) - .dockerignore 추가 - 헬스 체크 포함 ## Kubernetes 배포 - Deployment 및 Service 매니페스트 작성 - Replica: 1, Port: 8087 - Liveness/Readiness Probe 설정 - 리소스 제한: CPU 250m-1000m, Memory 512Mi-1024Mi ## Secret 및 ConfigMap - ai-secret: Claude API Key - azure-secret: Event Hub Connection String (AI Listen Policy) - redis-config/redis-secret: Redis 연결 정보 ## Ingress 설정 - /api/ai/suggestions 경로 추가 (ai-service:8087) - 기존 /api/ai 경로 유지 (ai:8080) ## 배포 문서 - DEPLOYMENT.md: 상세한 AKS 배포 가이드 - Docker 이미지 빌드 및 푸시 - Secret/ConfigMap 생성 - 배포 및 검증 - 트러블슈팅 ## ACR 이미지 - acrdigitalgarage02.azurecr.io/hgzero/ai-service:latest 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .github/kustomize/base/common/ingress.yaml | 7 + ai-python/.dockerignore | 35 +++ ai-python/API-DOCUMENTATION.md | 16 +- ai-python/DEPLOYMENT.md | 318 +++++++++++++++++++++ ai-python/Dockerfile | 27 ++ ai-python/main.py | 7 +- deploy/k8s/backend/ai-secret-template.yaml | 27 ++ deploy/k8s/backend/ai-service.yaml | 130 +++++++++ 8 files changed, 556 insertions(+), 11 deletions(-) create mode 100644 ai-python/.dockerignore create mode 100644 ai-python/DEPLOYMENT.md create mode 100644 ai-python/Dockerfile create mode 100644 deploy/k8s/backend/ai-secret-template.yaml create mode 100644 deploy/k8s/backend/ai-service.yaml diff --git a/.github/kustomize/base/common/ingress.yaml b/.github/kustomize/base/common/ingress.yaml index 6ac515e..2c9fc92 100644 --- a/.github/kustomize/base/common/ingress.yaml +++ b/.github/kustomize/base/common/ingress.yaml @@ -32,6 +32,13 @@ spec: name: stt port: number: 8080 + - path: /api/ai/suggestions + pathType: Prefix + backend: + service: + name: ai-service + port: + number: 8087 - path: /api/ai pathType: Prefix backend: diff --git a/ai-python/.dockerignore b/ai-python/.dockerignore new file mode 100644 index 0000000..715b82f --- /dev/null +++ b/ai-python/.dockerignore @@ -0,0 +1,35 @@ +# Python +__pycache__/ +*.py[cod] +*$py.class +*.so +.Python +venv/ +env/ +ENV/ + +# IDE +.vscode/ +.idea/ +*.swp +*.swo + +# Logs +logs/ +*.log + +# Environment +.env +.env.local + +# Git +.git/ +.gitignore + +# Documentation +README.md +API-DOCUMENTATION.md + +# Test +tests/ +test_*.py diff --git a/ai-python/API-DOCUMENTATION.md b/ai-python/API-DOCUMENTATION.md index ca78f2b..0a15167 100644 --- a/ai-python/API-DOCUMENTATION.md +++ b/ai-python/API-DOCUMENTATION.md @@ -11,7 +11,7 @@ ### 1. 실시간 AI 제안사항 스트리밍 (SSE) -**엔드포인트**: `GET /api/v1/ai/suggestions/meetings/{meeting_id}/stream` +**엔드포인트**: `GET /api/ai/suggestions/meetings/{meeting_id}/stream` **설명**: 회의 중 실시간으로 AI 제안사항을 Server-Sent Events로 스트리밍합니다. @@ -49,7 +49,7 @@ interface RealtimeSuggestionsResponse { // EventSource 연결 const meetingId = 'meeting-123'; const eventSource = new EventSource( - `http://localhost:8087/api/v1/ai/suggestions/meetings/${meetingId}/stream` + `http://localhost:8087/api/ai/suggestions/meetings/${meetingId}/stream` ); // AI 제안사항 수신 @@ -95,7 +95,7 @@ function MeetingRoom({ meetingId }: { meetingId: string }) { useEffect(() => { const eventSource = new EventSource( - `http://localhost:8087/api/v1/ai/suggestions/meetings/${meetingId}/stream` + `http://localhost:8087/api/ai/suggestions/meetings/${meetingId}/stream` ); eventSource.addEventListener('ai-suggestion', (event) => { @@ -156,8 +156,8 @@ function MeetingRoom({ meetingId }: { meetingId: string }) { "version": "1.0.0", "status": "running", "endpoints": { - "test": "/api/v1/ai/suggestions/test", - "stream": "/api/v1/ai/suggestions/meetings/{meeting_id}/stream" + "test": "/api/ai/suggestions/test", + "stream": "/api/ai/suggestions/meetings/{meeting_id}/stream" } } ``` @@ -210,13 +210,13 @@ function MeetingRoom({ meetingId }: { meetingId: string }) { curl http://localhost:8087/health # SSE 스트리밍 테스트 -curl -N http://localhost:8087/api/v1/ai/suggestions/meetings/test-meeting/stream +curl -N http://localhost:8087/api/ai/suggestions/meetings/test-meeting/stream ``` ### 브라우저 테스트: 1. 서비스 실행: `python3 main.py` 2. Swagger UI 접속: http://localhost:8087/docs -3. `/api/v1/ai/suggestions/meetings/{meeting_id}/stream` 엔드포인트 테스트 +3. `/api/ai/suggestions/meetings/{meeting_id}/stream` 엔드포인트 테스트 ## 환경 변수 @@ -231,7 +231,7 @@ NEXT_PUBLIC_AI_SERVICE_URL=http://localhost:8087 const AI_SERVICE_URL = process.env.NEXT_PUBLIC_AI_SERVICE_URL || 'http://localhost:8087'; const eventSource = new EventSource( - `${AI_SERVICE_URL}/api/v1/ai/suggestions/meetings/${meetingId}/stream` + `${AI_SERVICE_URL}/api/ai/suggestions/meetings/${meetingId}/stream` ); ``` diff --git a/ai-python/DEPLOYMENT.md b/ai-python/DEPLOYMENT.md new file mode 100644 index 0000000..27b255f --- /dev/null +++ b/ai-python/DEPLOYMENT.md @@ -0,0 +1,318 @@ +# 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= \ + --docker-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`보다 먼저 정의되어야 함 + - 더 구체적인 경로를 위에 배치 diff --git a/ai-python/Dockerfile b/ai-python/Dockerfile new file mode 100644 index 0000000..3c633c4 --- /dev/null +++ b/ai-python/Dockerfile @@ -0,0 +1,27 @@ +# Python 3.11 slim 이미지 사용 +FROM python:3.11-slim + +# 작업 디렉토리 설정 +WORKDIR /app + +# 시스템 패키지 업데이트 및 필요한 도구 설치 +RUN apt-get update && apt-get install -y \ + gcc \ + && rm -rf /var/lib/apt/lists/* + +# Python 의존성 파일 복사 및 설치 +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt + +# 애플리케이션 코드 복사 +COPY . . + +# 포트 노출 +EXPOSE 8087 + +# 헬스 체크 +HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \ + CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8087/health')" || exit 1 + +# 애플리케이션 실행 +CMD ["python", "main.py"] diff --git a/ai-python/main.py b/ai-python/main.py index e1fc02c..1a6a468 100644 --- a/ai-python/main.py +++ b/ai-python/main.py @@ -84,7 +84,7 @@ app.add_middleware( # 라우터 등록 app.include_router( suggestions.router, - prefix="/api/v1/ai/suggestions", + prefix="/api/ai/suggestions", tags=["AI Suggestions"] ) @@ -97,8 +97,9 @@ async def root(): "version": "1.0.0", "status": "running", "endpoints": { - "test": "/api/v1/ai/suggestions/test", - "stream": "/api/v1/ai/suggestions/meetings/{meeting_id}/stream" + "test": "/api/ai/suggestions/test", + "stream": "/api/ai/suggestions/meetings/{meeting_id}/stream", + "swagger": "/swagger-ui.html" } } diff --git a/deploy/k8s/backend/ai-secret-template.yaml b/deploy/k8s/backend/ai-secret-template.yaml new file mode 100644 index 0000000..8b19506 --- /dev/null +++ b/deploy/k8s/backend/ai-secret-template.yaml @@ -0,0 +1,27 @@ +--- +# AI Service Secret Template +# 실제 배포 시 base64로 인코딩된 값으로 교체 필요 +apiVersion: v1 +kind: Secret +metadata: + name: ai-secret + namespace: hgzero +type: Opaque +data: + # Claude API Key (base64 인코딩 필요) + # echo -n "sk-ant-api03-..." | base64 + claude-api-key: + +--- +# Azure EventHub Secret for AI Service +# AI 서비스용 Event Hub 연결 문자열 +apiVersion: v1 +kind: Secret +metadata: + name: azure-secret + namespace: hgzero +type: Opaque +data: + # Event Hub Connection String (AI Listen Policy) + # echo -n "Endpoint=sb://..." | base64 + eventhub-ai-connection-string: diff --git a/deploy/k8s/backend/ai-service.yaml b/deploy/k8s/backend/ai-service.yaml new file mode 100644 index 0000000..6e90226 --- /dev/null +++ b/deploy/k8s/backend/ai-service.yaml @@ -0,0 +1,130 @@ +--- +# AI Service (Python) Deployment +apiVersion: apps/v1 +kind: Deployment +metadata: + name: ai-service + namespace: hgzero + labels: + app: ai-service + tier: backend + language: python +spec: + replicas: 1 + selector: + matchLabels: + app: ai-service + template: + metadata: + labels: + app: ai-service + tier: backend + language: python + spec: + containers: + - name: ai-service + image: acrdigitalgarage02.azurecr.io/hgzero/ai-service:latest + imagePullPolicy: Always + ports: + - containerPort: 8087 + name: http + env: + # 서버 설정 + - name: PORT + value: "8087" + - name: HOST + value: "0.0.0.0" + - name: LOG_LEVEL + value: "INFO" + + # Claude API + - name: CLAUDE_API_KEY + valueFrom: + secretKeyRef: + name: ai-secret + key: claude-api-key + - name: CLAUDE_MODEL + value: "claude-3-5-sonnet-20241022" + - name: CLAUDE_MAX_TOKENS + value: "2000" + - name: CLAUDE_TEMPERATURE + value: "0.3" + + # Redis + - name: REDIS_HOST + valueFrom: + configMapKeyRef: + name: redis-config + key: host + - name: REDIS_PORT + valueFrom: + configMapKeyRef: + name: redis-config + key: port + - name: REDIS_PASSWORD + valueFrom: + secretKeyRef: + name: redis-secret + key: password + - name: REDIS_DB + value: "4" + + # Azure Event Hub + - name: EVENTHUB_CONNECTION_STRING + valueFrom: + secretKeyRef: + name: azure-secret + key: eventhub-ai-connection-string + - name: EVENTHUB_NAME + value: "hgzero-eventhub-name" + - name: EVENTHUB_CONSUMER_GROUP + value: "$Default" + + # CORS + - name: CORS_ORIGINS + value: '["*"]' + + resources: + requests: + cpu: 250m + memory: 512Mi + limits: + cpu: 1000m + memory: 1024Mi + + livenessProbe: + httpGet: + path: /health + port: 8087 + initialDelaySeconds: 30 + periodSeconds: 10 + timeoutSeconds: 5 + failureThreshold: 3 + + readinessProbe: + httpGet: + path: /health + port: 8087 + initialDelaySeconds: 10 + periodSeconds: 5 + timeoutSeconds: 3 + failureThreshold: 3 + +--- +# AI Service Service +apiVersion: v1 +kind: Service +metadata: + name: ai-service + namespace: hgzero + labels: + app: ai-service +spec: + type: ClusterIP + ports: + - port: 8087 + targetPort: 8087 + protocol: TCP + name: http + selector: + app: ai-service