Deployment

Deployment

백엔드는 OCI 위의 k3s 클러스터에 GitOps 방식으로 배포한다.

k3s는 경량 Kubernetes 배포판이다. 따라서 Deployment, Service, Ingress, Kustomize 같은 표준 Kubernetes API를 쓰지만, 실제 운영 클러스터와 네트워크 운영 주체는 k3s이다.

역할 분리

위치	담당
dnd-15th-3-backend	Dockerfile, GHCR 이미지, deploy/k8s 매니페스트, 환경별 이미지 태그
ArgoCD	이 레포의 배포 매니페스트 감시 및 k3s 반영
인프라 관리자 전용 레포	k3s namespace, ArgoCD Project/RBAC, Cloudflare Tunnel/Access 설정

팀원은 이 백엔드 레포만 수정한다. 인프라 관리자 레포나 운영 클러스터에 직접 kubectl apply하지 않는다.

환경

Git branch	k3s namespace	Kustomize overlay	API hostname	용도
develop	dnd-15th-3-dev	deploy/k8s/overlays/develop	momo-dev.jinmu.me	팀 통합 개발 환경
main	dnd-15th-3	deploy/k8s/overlays/main	momo.jinmu.me	안정 배포 환경

기능 브랜치는 develop으로 PR을 보내고, 검증된 develop은 main으로 PR을 보낸다.

배포 흐름

feature branch PR → develop merge
  → GitHub Actions: linux/arm64 이미지 build
  → GHCR: develop-<commit-sha> push
  → deploy/k8s/overlays/develop 이미지 태그 commit
  → ArgoCD가 변경 감지
  → k3s dnd-15th-3-dev namespace rollout

develop → main PR도 같은 흐름으로 main 환경에 배포

이미지 태그는 develop-<sha> 또는 main-<sha>의 불변 태그다. latest를 사용하지 않으므로, 어느 코드가 실행 중인지 Git과 ArgoCD에서 추적하고 이전 SHA로 롤백할 수 있다.

팀원이 수정하는 파일

Dockerfile                         # 애플리케이션 컨테이너
.github/workflows/image.yml        # ARM build + 배포 태그 갱신
deploy/k8s/base/                   # 공통 Deployment, Service, Ingress
deploy/k8s/overlays/develop/       # develop 환경 차이
deploy/k8s/overlays/main/          # main 환경 차이
deploy/sealed-secrets.pub.pem      # Secret 암호화용 공개 인증서

배포된 앱은 /api/docs에서 Swagger UI를 제공한다. API 명세는 배포 후 해당 경로에서 확인한다.

현재 readiness/liveness/startup probe는 다음 health endpoint를 사용한다.

엔드포인트	용도	확인 항목
GET /health	App level 종합 상태	DB + OCI Storage
GET /health/live	Liveness probe	프로세스 생존
GET /health/ready	Readiness probe	DB + OCI Storage
GET /health/startup	Startup probe	프로세스 생존

liveness와 startup은 외부 의존성 장애로 인해 Pod가 재시작되는 것을 방지하기 위해 프로세스 생존 여부만 확인한다. readiness는 트래픽 수신 가능 여부를 판단하므로 DB와 OCI Storage 연결 상태를 함께 확인한다.

새 기능이 시작 의존성(DB 등)을 추가하면 readiness와 /health 기준도 함께 갱신한다.

시크릿

평문 .env, API 키, DB 비밀번호는 commit/PR/채팅에 올리지 않는다. 필요한 값은 공개 인증서로 SealedSecret을 만들고 암호화된 파일만 환경 overlay에 추가한다.

kubeseal --format=yaml --cert deploy/sealed-secrets.pub.pem \
  < secret.plain.yaml > deploy/k8s/overlays/develop/secret.sealed.yaml
rm secret.plain.yaml

공개 인증서는 암호화만 가능하고 복호화는 불가하다. 실제 Secret 값은 k3s의 sealed-secrets controller만 복호화한다.

확인과 장애 전달

• ArgoCD dnd-viewer 계정은 DND 앱과 로그만 read-only로 볼 수 있다.
• 배포 후 /health가 200 OK이고 모든 의존성이 status: "up"인지 확인한다.
• ImagePullBackOff, CrashLoopBackOff, PVC Pending, Secret 누락은 ArgoCD 상태와 이벤트를 첨부해 인프라 관리자에게 전달한다.
• 앱을 멈추려면 Deployment replica 또는 CronJob suspend를 Git PR로 변경한다. UI에서 Delete/Sync하지 않는다.
• 영구 삭제는 PVC까지 지울 수 있으므로 팀원이 단독으로 진행하지 않는다.

첫 배포 전 관리자 체크

1. GitHub Actions의 GHCR package write 권한과 public package visibility 확인
2. ArgoCD Application이 develop/main overlay를 각각 감시하도록 등록
3. Cloudflare Tunnel에 momo-dev.jinmu.me, momo.jinmu.me hostname 추가
4. ArgoCD dnd-viewer 계정과 Cloudflare Access 이메일 allowlist 설정