Repository navigation
Incident Runbook
Alertmanager 알림 수신 후 진단·복구 절차. 셀프 호스트 운영 시 필수 문서.
| 원칙 | 설명 |
|---|---|
| 관측 → 진단 → 조치 → 기록 | Grafana에서 문제 범위 확인 → 원인 파악 → 조치 → 타임라인 기록 |
| Severity 기준 우선순위 | critical은 즉시, warning은 근무 시간 내 |
| Git 우선 | 인프라 변경은 Git 커밋 → ArgoCD 동기화. kubectl edit 직접 수정 금지 |
| 사후 기록 | 재발 가능성 있는 장애는 본 문서 §5에 사례 추가 |
알림을 받으면 다음 순서로 정보를 수집한다.
- 알림 페이로드 확인 — Discord 메시지에서 알림명·severity·대상 리소스 확인
-
Grafana 대시보드 열기 — 전체 상태 파악
-
Kubernetes Cluster Overview(노드·Pod 상태) -
BE Application(애플리케이션 메트릭) -
Istio Service Mesh(트래픽·에러율)
-
- 관련 로그 조회 — 알림이 가리키는 시각 ±10분 Loki 쿼리
-
최근 배포 확인 — ArgoCD UI 또는
gh run list로 최근 CD 상태 확인
의미: 애플리케이션 Pod가 1분 이상 Ready 상태가 아님
진단
1. ArgoCD에서 최근 배포 여부 확인 (잘못된 이미지 digest)
2. kubectl describe pod -n orino <pod> → Events·Conditions 확인
3. kubectl logs -n orino <pod> --previous → 크래시 직전 로그
조치
- 배포 직후라면 ArgoCD에서 이전 ApplicationSet rollback
- OOM이면
values.yaml의resources.limits.memory상향 커밋 - ImagePull 실패면 GHCR 인증·네트워크 확인
의미: 데이터 계층 Pod Down
MySQL Down 진단
1. kubectl describe pod -n orino mysql-0 → PVC mount, resource 상태
2. Longhorn UI → MySQL volume 상태 (Degraded? Attached?)
3. 노드 상태 (mysql-0이 스케줄된 노드가 NotReady인가)
MySQL 조치
- PVC mount 실패: Longhorn 볼륨 확인 → 필요 시 replica에서 복원
- 노드 장애: StatefulSet이 다른 노드에서 재시작되도록 taint/toleration 확인
- 디스크 부족:
NodeDiskSpaceLow와 함께 발생 시 오래된 이미지 정리 or 노드 증설
Redis Down: 세션 데이터만 있으므로 재기동 우선. 데이터 유실 시 모든 사용자 재로그인으로 복구.
의미: 노드가 5분 이상 NotReady
진단
1. kubectl get nodes → 전체 노드 상태
2. kubectl describe node <node> → Conditions·Events
3. SSH로 노드 접속 (`ssh note1` 등) → kubelet·containerd 상태
조치
- kubelet/containerd 재시작:
systemctl restart kubelet - 디스크 부족:
docker system prune, 로그 로테이션 확인 - 영구 장애: Longhorn이 replica를 다른 노드에 재구성 중인지 확인 → 완료 후 노드 교체
의미: Pod가 5분간 재시작 반복
진단 & 조치: BackendDown과 동일 절차. 근본 원인이 config 오류인 경우가 많음.
의미: 10분 이상 replica 수 불일치
진단
1. kubectl get deploy -A → 어느 Deployment인지
2. kubectl describe deploy -n <ns> <name> → rollout 상태
3. 스케줄 실패(노드 리소스 부족) 또는 ImagePull 실패 대부분
의미: Longhorn RecurringJob(backup) 실패
진단
1. Longhorn UI → Recurring Jobs → 실패 로그
2. backupTarget(S3) 접근 가능 여부, 용량
3. S3 credentials 유효성
※ 현재 orino는 MySQL 백업에 Longhorn backup을 사용하지 않음 (Backup-Recovery §4 참조). 이 알림은 향후 Longhorn backup 도입 시 유효.
warning은 근무 시간 내 대응. 방치 시 critical로 전이되므로 트렌드 추적 필수.
| 알림 | 주된 원인 | 조치 |
|---|---|---|
| PodOOMKilled | memory limit 부족, 메모리 누수 | Grafana에서 heap 추이 확인 → limit 조정 or 코드 수정 |
| PodNotReady | readinessProbe 실패 | startupProbe initialDelaySeconds 조정, 의존성(DB) 상태 확인 |
| ContainerMemoryNearLimit | 점진적 증가 | 일시적이면 observe, 계속 증가면 leak 의심 |
| NodeHighCpuUsage | 특정 Pod의 CPU hog | kubectl top pods -A --sort-by=cpu |
| NodeHighMemoryUsage | 메모리 파편화 또는 과다 Pod |
kubectl top nodes, eviction 준비 |
| NodeDiskSpaceLow | 로그·이미지 누적 | containerd GC 확인, 오래된 이미지 삭제 |
| LonghornVolumeDegrade | replica 소실 | 자동 재생성 대기, 30분 내 미복구 시 수동 |
| PvcUsageHigh | 데이터 증가 | PVC expand (Longhorn 지원) 또는 데이터 정리 |
자주 쓰는 Grafana/Loki/PromQL 쿼리.
# BE 에러 로그 (최근 1시간)
{namespace="orino", app="orino-be"} |= "ERROR"
# 특정 traceId 추적
{namespace="orino"} | json | traceId="abc123"
# HTTP 5xx만
{namespace="orino", app="orino-be"} | json | status >= 500
# BE HTTP 5xx 비율 (5분)
sum(rate(http_server_requests_seconds_count{namespace="orino",status=~"5.."}[5m]))
/ sum(rate(http_server_requests_seconds_count{namespace="orino"}[5m]))
# JVM heap 사용률
jvm_memory_used_bytes{area="heap"} / jvm_memory_max_bytes{area="heap"}
# DB 커넥션 풀 사용률
hikaricp_connections_active / hikaricp_connections_max
재발 방지를 위해 주요 장애를 기록한다. 사례가 쌓이면 §3 대응 절차를 보강한다.
포맷
### YYYY-MM-DD: 장애 제목 - 증상: 어떤 알림이 울렸고 사용자 체감 영향은 무엇이었는지 - 원인: 근본 원인 - 조치: 구체적 복구 절차 - 재발 방지: 알림 추가, 설정 변경 등
-
증상: 새 FE 배포 직후 일부 사용자 브라우저에서 화면이 안 뜨고 콘솔에
Failed to load module script: Expected a JavaScript-or-Wasm module script but the server responded with a MIME type of "text/html".- 브라우저 캐시 비우기·강력 새로고침·시크릿 모드로도 동일하게 재현됨 (= 브라우저 캐시 문제 아님)
- 운영자(다른 지역)에게는 멀쩡하고 특정 사용자에게만 발생 (POP별 차이)
-
원인: SPA fallback + Cloudflare 캐시의 조합
-
fe/nginx.conf이try_files $uri $uri/ /index.html하나라, 없는/assets/*.js해시 요청에 404가 아니라index.html(200,text/html) 을 반환. - PR 다수를 짧게 연속 머지해 FE가 여러 번 롤링 배포되는 동안, 브라우저가 새 해시 asset을 요청했는데 아직 안 뜬 옛 파드에 닿아 잠깐씩 404 → HTML 셸(200) 을 받음.
-
Cloudflare는 MIME이 아니라 파일 확장자(
.js)로 캐시하므로, 그text/html응답을.jsURL에 캐시. 사용자 POP 엣지 캐시에 HTML이index-*.js로 박힘(max-age=14400= 4h). - index.html은 캐시 안 됨(DYNAMIC)이라 매번 최신 해시를 가리키지만, 그 해시 asset이 사용자 POP에선 오염된 HTML로 응답 → module MIME 에러.
- Origin은 정상(두 파드 모두 파일 보유, CF 우회 클러스터 내부 요청도 정상 JS). 즉 엣지 캐시 오염이지 origin/빌드 문제 아님.
-
-
조치:
- Cloudflare 캐시 퍼지 (Dashboard → Caching → Configuration → Purge Everything). 엣지 캐시를 비우는 게 유일한 즉시 복구. 브라우저 캐시 클리어·재배포(같은 해시면 같은 URL이라 무효)로는 안 됨.
- 진단 명령
# 없는 asset이 404가 아닌 text/html을 반환하는지 (SPA fallback 버그 확인) curl -sI https://orino.dev/assets/index-DOESNOTEXIST.js # 200 text/html 이면 버그 # origin(클러스터 내부, CF 우회)이 정상 JS를 주는지 kubectl run cfbypass --rm -i --restart=Never --image=curlimages/curl -n orino -- \ -sI http://fe.orino.svc.cluster.local/assets/<현재해시>.js # application/javascript 기대
-
재발 방지:
fe/nginx.conf에서 (PR #424)-
/assets/는try_files $uri =404로 없는 파일은 404 (HTML 셸 폴백 차단 → CF가 HTML을.js로 캐시하는 일 원천 차단), 해시 파일명이므로Cache-Control: public, max-age=31536000, immutable. -
index.html은Cache-Control: no-cache, no-store, must-revalidate로 캐시 금지(배포마다 최신 해시 참조).
-
ℹ️ 2026-06-15 이후 현행 참고 (ELOG-009): Cloudflare를 완전 제거하고 집 회선 직결로 전환했다. 따라서 위 엣지 캐시 오염·"Cloudflare 캐시 퍼지" 조치는 더 이상 적용되지 않는다(CF POP 캐시 자체가 없음). 근본 원인인 SPA fallback 버그는 PR #424(
try_files $uri =404)로 이미 차단됐으므로, 동일 증상 재발 시엔 nginx 설정과 롤링 배포 중 옛 파드 응답만 확인하면 된다.
현재 단일 운영자. 외부 에스컬레이션 대상 없음.
향후 고려:
- critical 알림 2회 이상 자동 재시도 실패 → SMS/전화 알림 추가 (Twilio 등)
- 장기 부재 대비 온콜 대리인 지정 절차
- 관측성 (Observability) §10 Alerting, §11 SLO
- 백업·복구 전략 — 데이터 복구 절차
- 인프라 아키텍처