Postgre HA 구성 용어 정리

Postgres 고가용성(HA) 구성할 때 HAProxy / Patroni / etcd 각 역할이랑 동작 방식 헷갈려서 정리해둠.

 

역할 한줄 요약

• HAProxy: 트래픽 길잡이. 8008 포트로 찔러보고 200 OK 내는 DB로 트래픽(5000/5001) 보내줌.
• Patroni: DB 매니저. etcd 눈치 보면서 local Postgres 상태(pg_is_in_recovery()) 제어하고, 8008 포트 REST API 열어둠.
• etcd: 중앙 열쇠고리. 분산 Lock 걸어서 Master DB가 2개 이상 생기는 뇌분리(Split-Brain) 현상 막아줌.

 

누가 Master인가? 판단 흐름

Patroni가 알아서 주도권 잡고 HAProxy가 그거 따라가는 구조임.

1. etcd 분산 Lock 획득
   • etcd에 /leader 키 선착순 등록.
   • Lock을 잡은 노드의 Patroni가 "내가 Master"라고 인지함. (3초마다 연장 신호 보냄)
2. Patroni의 DB 상태 체크
   • Patroni가 자기 DB에 SELECT pg_is_in_recovery(); 쿼리를 지속적으로 날림.
   • etcd Lock을 잡고 있고 + DB가 Read/Write 모드면 /primary 호출 시 200 OK 응답을 뱉음.
   • Lock을 못 잡은 Replica 노드는 /primary 요청에 503 Error 보냄.
3. HAProxy 라우팅
   • HAProxy는 각 DB 노드의 8008 포트(/primary)를 주기적으로 찔러봄.
   • 200 OK 떨어지는 노드로 쓰기(Write) 트래픽 전달.
4.  

Primary 죽었을 때 (Failover)

1. Primary 서버 다운됨 → etcd로 가던 Heartbeat 끊김 (10초 뒤 Lock 자동 삭제).
2. 살아있는 Replica 노드들의 Patroni가 etcd Lock 잡으려고 경합함.
3. etcd Raft 알고리즘으로 딱 1개 노드만 Lock 획득 성공.
4. Lock 잡은 노드가 자기 Postgres를 Read/Write 모드로 승격시킴.
5. HAProxy 헬스체크에 승격된 노드만 200 OK 뜨면서 트래픽이 알아서 새 Master로 붙음.

 

4. 자주 쓰는 확인 명령어

# Patroni 클러스터 상태 확인
sudo patronictl -c /etc/patroni/config.yml list

# 8008 헬스체크 직접 찔러보기 (Master만 200 OK 뜸)
curl -s -i http://127.0.0.1:8008/primary

요약

etcd가 열쇠 쥐고 있고, Patroni가 DB 쿼리+열쇠로 상태 판별하고, HAProxy는 8008 포트 찔러서 트래픽 연결해주는 구조.