2.3 장애 모델

CloudNativePG의 장애 처리는 특별한 마법이 아니라 Kubernetes의 표준 동작 위에 self-healing을 얹은 것이다. 대부분의 장애는 조정 루프가 “원하는 상태와 현재 상태의 차이"를 감지해 자동으로 메운다. 여기서는 어떤 장애가 자동으로 복구되고, 어떤 경우에 사람이 개입해야 하는지를 구분해 정리한다.

자동 복구 (self-healing)

primary Pod 장애

primary가 죽으면 failover가 시작된다.

    flowchart TD
  FAIL["primary 장애 감지"]
  PICK["최신 standby 선정<br/>(지연 최소)"]
  PROMO["새 primary로 승격"]
  SVC["-rw 서비스 갱신"]
  REPL["나머지 replica<br/>새 primary 추종"]
  REJOIN{"기존 PVC 살아 있나"}
  REWIND["pg_rewind로 재합류"]
  REBUILD["백업에서 재생성"]

  FAIL --> PICK --> PROMO --> SVC --> REPL
  PROMO --> REJOIN
  REJOIN -->|예| REWIND
  REJOIN -->|아니오| REBUILD

  classDef node fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
  class FAIL,PICK,PROMO,SVC,REPL,REWIND,REBUILD node

Operator가 복제 지연이 가장 적은 최신 standby를 승격 후보로 고른다
그 standby를 새 primary로 승격한다
-rw 서비스를 새 primary로 돌리고, 죽은 Pod를 -r·-rw에서 뺀다
남은 replica들은 새 primary를 바라보고 복제를 잇는다
옛 primary는 PVC가 살아 있으면 pg_rewind로 다시 합류하고, PVC가 없으면 새 primary의 백업에서 재생성된다

replica Pod 장애

replica가 죽으면 더 단순하다.

해당 Pod를 -r·-ro 서비스에서 뺀다
기존 PVC가 있으면 그 PVC로 Pod를 재시작한다
PVC를 못 쓰면 현재 primary의 백업에서 새로 만든다
준비가 끝나면 다시 -r·-ro 서비스에 넣는다

replica 장애는 쓰기(primary)에 영향을 주지 않으므로 서비스 연속성 관점에서 영향이 작다.

PVC 장애, 노드 장애, 스토리지 이슈 같은 시나리오는 CloudNativePG 고유 로직이라기보다 Kubernetes 표준 동작을 따른다. 노드가 offline이 되면 그 위 Pod는 결국 스케줄에서 빠지고, primary였다면 위의 failover 절차가 돈다. 세부 동작은 Kubernetes 문서(node eviction, PVC 재바인딩 등)를 함께 참고한다.

자동으로 처리하지 않는 것

self-healing이 오히려 해로운 상황도 있다. 대표적인 것이 디스크 풀이다.

인스턴스 매니저는 스토리지가 고갈되면 failover를 트리거하지 않는다. 원인이 데이터 증가나 WAL 적체라면 다른 Pod로 옮겨도 같은 벽에 부딪히기 때문이다. 이때는 사람이 PVC 크기를 늘리고 Cluster 리소스를 맞춰 갱신해야 정상으로 돌아온다.

수동 개입: 조정 루프 멈추기

긴급 상황에서 Operator의 자동 조정이 오히려 방해가 될 때가 있다. 예를 들어 수동으로 데이터를 손보는 중인데 Operator가 자꾸 원래 상태로 되돌린다면 곤란하다. 이때는 조정 루프를 잠시 끈다.

# 특정 Cluster의 조정 루프를 일시 중지
kubectl annotate cluster pg cnpg.io/reconciliationLoop=disabled

# 작업이 끝나면 반드시 원복
kubectl annotate cluster pg cnpg.io/reconciliationLoop-

이 annotation은 Cluster·Backup 리소스에 적용된다.

reconciliationLoop=disabled는 Operator의 눈을 가리는 것이다. 이 상태에서는 자동 failover·self-healing이 모두 멈춘다. 긴급 작업에만 쓰고, 끝나는 즉시 annotation을 제거해 자동 운영을 되살려야 한다. 켜 둔 채로 방치하면 진짜 장애가 나도 아무도 복구하지 않는다.

정리

대부분의 장애는 조정 루프가 자동으로 메운다 — Kubernetes 표준 위의 self-healing
primary 장애: 최신 standby 승격 → -rw 갱신 → 옛 primary는 pg_rewind 또는 재생성
replica 장애: 서비스에서 제외 → PVC 재사용 또는 재생성 → 복귀. 쓰기 영향 없음
디스크 풀은 자동 failover하지 않는다 — 사람이 PVC를 늘려야 한다
긴급 수동 작업은 cnpg.io/reconciliationLoop=disabled로 조정을 멈추되, 끝나면 즉시 원복

여기까지 Part II에서 CloudNativePG의 아키텍처, 인스턴스 매니저, 장애 모델을 정리했다. 다음 Part III에서는 Operator를 실제로 설치하고 업그레이드하는 방법으로 넘어간다.

2.2 인스턴스 매니저