| name | cicd |
| description | 인프라 및 CI/CD 가이드. GKE Autopilot 배포, Firebase Hosting, GitHub Actions 워크플로우, 트러블슈팅. 트리거 키워드 - 배포, deploy, 인프라, infrastructure, GKE, CI/CD, 파이프라인, Kubernetes, kubectl |
Infrastructure & CI/CD Guide
GKE Autopilot + Firebase Hosting + GitHub Actions 기반 배포 가이드
1. 인프라 개요
| 컴포넌트 | 기술 | 용도 |
|---|
| Backend 런타임 | GKE Autopilot | NestJS 서비스 배포 |
| Frontend 호스팅 | Firebase Hosting | React 앱 배포 |
| 컨테이너 레지스트리 | Artifact Registry | Docker 이미지 저장 |
| 네트워크 | Terraform (VPC) | VPC, Subnet 관리 |
| DB | PostgreSQL (K8s StatefulSet) | 서비스별 DB |
| 메시지 브로커 | NATS (K8s Deployment) | 서비스 간 통신 |
| SSL | GKE ManagedCertificate | HTTPS 인증서 |
| 리전 | asia-northeast3 (서울) | - |
도메인
| 환경 | API | 프론트엔드 |
|---|
| dev | dev-api.parkgolfmate.com | Firebase 자동 URL |
| prod | api.parkgolfmate.com | Firebase 자동 URL |
2. GitHub Actions 워크플로우
| 파일 | 이름 | 용도 | 트리거 |
|---|
ci.yml | CI Pipeline | Lint, Test, Build, Security Scan | workflow_dispatch |
cd-services.yml | CD Services | Backend → GKE 배포 | workflow_dispatch |
cd-apps.yml | CD Apps | Frontend → Firebase 배포 | workflow_dispatch |
cd-infra.yml | CD Infrastructure | VPC/GKE 클러스터 관리 | workflow_dispatch |
3. 배포 전략
환경 분리
develop 브랜치 → dev 환경
main 브랜치 → prod 환경
선택적 서비스 배포
# CD Services 워크플로우에서 선택
services: "iam-service,course-service" # 쉼표 구분
services: "all" # 전체 배포
서비스 전체 목록
iam-service, course-service, booking-service, payment-service,
chat-service, notify-service, admin-api, user-api, chat-gateway,
weather-service, location-service, job-service, agent-service
4. Backend 배포 (cd-services.yml)
파이프라인
Setup → Build & Push (Docker → Artifact Registry) → Deploy (K8s) → Setup Ingress
서비스별 리소스
| 서비스 | CPU (req/lim) | Memory (req/lim) | DB |
|---|
| iam-service | 50m/250m | 128Mi/384Mi | iam_db |
| course-service | 50m/250m | 128Mi/384Mi | course_db |
| booking-service | 50m/250m | 128Mi/384Mi | booking_db |
| payment-service | 50m/250m | 128Mi/384Mi | payment_db |
| chat-service | 50m/250m | 128Mi/384Mi | chat_db |
| notify-service | 50m/250m | 128Mi/384Mi | notify_db |
| chat-gateway | 100m/300m | 128Mi/384Mi | - |
| job-service | 50m/200m | 64Mi/256Mi | - |
| 기타 (BFF, etc.) | 50m/250m | 128Mi/384Mi | - |
K8s Probe 설정
startupProbe: /health
readinessProbe: /health/ready
livenessProbe: /health/live
Ingress 라우팅
| 경로 | 서비스 |
|---|
/api/admin/* | admin-api |
/api/user/* | user-api |
/socket.io/*, /chat/*, /notification/* | chat-gateway |
/webhook/* | payment-service |
5. Frontend 배포 (cd-apps.yml)
파이프라인
Setup → Build (Vite) → Deploy (Firebase Hosting)
앱 목록
| 앱 | Firebase Site (dev) | Firebase Site (prod) |
|---|
| admin-dashboard | parkgolf-admin-dev | parkgolf-admin |
| platform-dashboard | parkgolf-platform-dev | parkgolf-platform |
| user-app-web | parkgolf-user-dev | parkgolf-user |
빌드 환경변수
VITE_API_URL → https://{env}-api.parkgolfmate.com
VITE_CHAT_SOCKET_URL → https://{env}-api.parkgolfmate.com
VITE_ENV → dev | prod
VITE_TOSS_CLIENT_KEY → GitHub Secret
VITE_KAKAO_JS_KEY → GitHub Secret
6. 인프라 관리 (cd-infra.yml)
Actions
| Action | 설명 |
|---|
status | VPC, GKE, Pod, Service, Ingress 상태 확인 |
network-apply | Terraform으로 VPC/Subnet 생성 |
gke-setup | GKE 클러스터 + PostgreSQL + NATS + Secrets/ConfigMap 생성 |
gke-update | Secrets/ConfigMap 업데이트 + Deployment 재시작 |
gke-destroy | GKE 클러스터 삭제 (dev만, confirm 필수) |
network-destroy | VPC/Subnet 삭제 (dev만, confirm 필수) |
K8s 리소스 구조
Namespace: parkgolf-{env}
├── Secret: parkgolf-secrets (JWT, DB, API Keys)
├── ConfigMap: parkgolf-config (NATS_URL, NODE_ENV, ...)
├── StatefulSet: postgres (PostgreSQL 15)
├── Deployment: nats (NATS 2.10)
├── Deployment: {service} × 13
├── Service: {service} × 13 (port 8080)
├── Ingress: parkgolf-ingress
├── ManagedCertificate: parkgolf-cert
└── BackendConfig: websocket-backend-config (chat-gateway)
7. CI Pipeline (ci.yml)
Setup → CI Apps (matrix) + CI Services (matrix) + Security Scan → CI Status
| 단계 | 내용 |
|---|
| CI Apps | npm ci → lint → typecheck → test → build |
| CI Services | npm ci → lint → test → build |
| Security Scan | Trivy (CRITICAL, HIGH) |
8. 트러블슈팅
Pod Pending
kubectl describe pod {pod-name} -n parkgolf-{env}
NATS 연결 실패
kubectl logs {service-pod} -n parkgolf-{env}
Ingress 접속 불가
kubectl get ingress -n parkgolf-{env}
kubectl describe ingress parkgolf-ingress -n parkgolf-{env}
DB 연결 실패
kubectl exec -it postgres-0 -n parkgolf-{env} -- psql -U parkgolf -l
이미지 Pull 실패
kubectl describe pod {pod-name} -n parkgolf-{env}
9. 유용한 명령어
kubectl
gcloud container clusters get-credentials parkgolf-{env}-cluster --region=asia-northeast3
kubectl get pods -n parkgolf-{env}
kubectl get svc -n parkgolf-{env}
kubectl get ingress -n parkgolf-{env}
kubectl logs -f deployment/{service} -n parkgolf-{env}
kubectl logs {pod-name} -n parkgolf-{env} --previous
kubectl rollout status deployment/{service} -n parkgolf-{env}
kubectl rollout restart deployment/{service} -n parkgolf-{env}
kubectl get secret parkgolf-secrets -n parkgolf-{env} -o jsonpath='{.data}'
kubectl get configmap parkgolf-config -n parkgolf-{env} -o yaml
kubectl exec -it postgres-0 -n parkgolf-{env} -- psql -U parkgolf -d {db_name}
kubectl port-forward svc/nats 8222:8222 -n parkgolf-{env}
gcloud
gcloud container clusters list
gcloud artifacts docker images list asia-northeast3-docker.pkg.dev/{project}/parkgolf
gcloud compute addresses list --global