Skip to content

Incident Runbook

wcorn edited this page Jul 5, 2026 · 4 revisions

장애 대응 런북

Alertmanager 알림 수신 후 진단·복구 절차. 셀프 호스트 운영 시 필수 문서.

1. 대응 원칙

원칙 설명
관측 → 진단 → 조치 → 기록 Grafana에서 문제 범위 확인 → 원인 파악 → 조치 → 타임라인 기록
Severity 기준 우선순위 critical은 즉시, warning은 근무 시간 내
Git 우선 인프라 변경은 Git 커밋 → ArgoCD 동기화. kubectl edit 직접 수정 금지
사후 기록 재발 가능성 있는 장애는 본 문서 §5에 사례 추가

2. 최초 진입 순서

알림을 받으면 다음 순서로 정보를 수집한다.

  1. 알림 페이로드 확인 — Discord 메시지에서 알림명·severity·대상 리소스 확인
  2. Grafana 대시보드 열기 — 전체 상태 파악
    • Kubernetes Cluster Overview (노드·Pod 상태)
    • BE Application (애플리케이션 메트릭)
    • Istio Service Mesh (트래픽·에러율)
  3. 관련 로그 조회 — 알림이 가리키는 시각 ±10분 Loki 쿼리
  4. 최근 배포 확인 — ArgoCD UI 또는 gh run list로 최근 CD 상태 확인

3. 알림별 대응

3.1 critical

BackendDown / FrontendDown

의미: 애플리케이션 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 인증·네트워크 확인

MysqlDown / RedisDown

의미: 데이터 계층 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: 세션 데이터만 있으므로 재기동 우선. 데이터 유실 시 모든 사용자 재로그인으로 복구.

NodeNotReady

의미: 노드가 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를 다른 노드에 재구성 중인지 확인 → 완료 후 노드 교체

PodCrashLoopBackOff

의미: Pod가 5분간 재시작 반복

진단 & 조치: BackendDown과 동일 절차. 근본 원인이 config 오류인 경우가 많음.

DeploymentReplicasMismatch

의미: 10분 이상 replica 수 불일치

진단

1. kubectl get deploy -A → 어느 Deployment인지
2. kubectl describe deploy -n <ns> <name> → rollout 상태
3. 스케줄 실패(노드 리소스 부족) 또는 ImagePull 실패 대부분

LonghornBackupFailed

의미: Longhorn RecurringJob(backup) 실패

진단

1. Longhorn UI → Recurring Jobs → 실패 로그
2. backupTarget(S3) 접근 가능 여부, 용량
3. S3 credentials 유효성

※ 현재 orino는 MySQL 백업에 Longhorn backup을 사용하지 않음 (Backup-Recovery §4 참조). 이 알림은 향후 Longhorn backup 도입 시 유효.

3.2 warning

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 지원) 또는 데이터 정리

4. 진단 쿼리 모음

자주 쓰는 Grafana/Loki/PromQL 쿼리.

Loki

# BE 에러 로그 (최근 1시간)
{namespace="orino", app="orino-be"} |= "ERROR"

# 특정 traceId 추적
{namespace="orino"} | json | traceId="abc123"

# HTTP 5xx만
{namespace="orino", app="orino-be"} | json | status >= 500

PromQL

# 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

5. 과거 장애 사례

재발 방지를 위해 주요 장애를 기록한다. 사례가 쌓이면 §3 대응 절차를 보강한다.

포맷

### YYYY-MM-DD: 장애 제목
- 증상: 어떤 알림이 울렸고 사용자 체감 영향은 무엇이었는지
- 원인: 근본 원인
- 조치: 구체적 복구 절차
- 재발 방지: 알림 추가, 설정 변경 등

2026-06-01: FE 배포 후 Failed to load module script (MIME) 로 접속 불가

  • 증상: 새 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 캐시의 조합

    1. fe/nginx.conf이 try_files $uri $uri/ /index.html 하나라, 없는 /assets/*.js 해시 요청에 404가 아니라 index.html(200, text/html) 을 반환.
    2. PR 다수를 짧게 연속 머지해 FE가 여러 번 롤링 배포되는 동안, 브라우저가 새 해시 asset을 요청했는데 아직 안 뜬 옛 파드에 닿아 잠깐씩 404 → HTML 셸(200) 을 받음.
    3. Cloudflare는 MIME이 아니라 파일 확장자(.js)로 캐시하므로, 그 text/html 응답을 .js URL에 캐시. 사용자 POP 엣지 캐시에 HTML이 index-*.js로 박힘(max-age=14400 = 4h).
    4. index.html은 캐시 안 됨(DYNAMIC)이라 매번 최신 해시를 가리키지만, 그 해시 asset이 사용자 POP에선 오염된 HTML로 응답 → module MIME 에러.
    • Origin은 정상(두 파드 모두 파일 보유, CF 우회 클러스터 내부 요청도 정상 JS). 즉 엣지 캐시 오염이지 origin/빌드 문제 아님.
  • 조치:

    1. Cloudflare 캐시 퍼지 (Dashboard → Caching → Configuration → Purge Everything). 엣지 캐시를 비우는 게 유일한 즉시 복구. 브라우저 캐시 클리어·재배포(같은 해시면 같은 URL이라 무효)로는 안 됨.
    2. 진단 명령
      # 없는 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 설정과 롤링 배포 중 옛 파드 응답만 확인하면 된다.

6. 에스컬레이션

현재 단일 운영자. 외부 에스컬레이션 대상 없음.

향후 고려:

  • critical 알림 2회 이상 자동 재시도 실패 → SMS/전화 알림 추가 (Twilio 등)
  • 장기 부재 대비 온콜 대리인 지정 절차

7. 관련 문서

Clone this wiki locally