1.4 5분 Quickstart

Patroni 공식 저장소에는 docker compose 데모가 들어 있다. 명령 몇 개로 etcd 3노드, Patroni 3노드, HAProxy 1대 구성의 클러스터가 로컬에 뜬다. 1.2에서 글로 읽은 leader 선출과 자동 failover를 직접 눈으로 확인하는 것이 이 절의 목표다.

이 데모는 저장소 README가 밝히듯 Patroni 개발 보조와 빠른 테스트를 위한 것이다. 구성을 그대로 production에 옮기는 용도가 아니다.

데모 구성

컨테이너는 모두 일곱 대다. demo-etcd1에서 3까지가 DCS, demo-patroni1에서 3까지가 각자 PostgreSQL을 품은 Patroni 노드, demo-haproxy가 클라이언트 진입점이다. 클러스터 이름(PATRONI_SCOPE)은 demo이고, 호스트에 노출되는 포트는 HAProxy의 5000(primary)과 5001(정상 standby들로 load balance) 둘뿐이다.

    flowchart TD
  CLI["psql 클라이언트"] -->|"5000 (primary)"| HAP["demo-haproxy"]
  CLI -->|"5001 (replica)"| HAP
  HAP --> P1["demo-patroni1"]
  HAP --> P2["demo-patroni2"]
  HAP --> P3["demo-patroni3"]
  P1 --> E["demo-etcd1~3"]
  P2 --> E
  P3 --> E

띄우기

저장소 clone과 이미지 빌드

git clone https://github.com/patroni/patroni.git
cd patroni
docker build -t patroni .

빌드한 이미지 하나를 Patroni 컨테이너 세 대가 공유한다.

클러스터 기동

docker compose up -d

compose 파일은 저장소 루트의 docker-compose.yml이다. 잠시 뒤 docker ps로 일곱 개 컨테이너가 떠 있는지 확인한다.

클러스터 상태 확인

docker exec -ti demo-patroni1 bash
patronictl list

patronictl list는 클러스터 member들의 역할과 상태를 표로 출력한다. 세 member 중 어느 것이 Leader인지 여기서 확인해 둔다.

DCS 키 확인

같은 컨테이너 안에서 이어서 실행한다.

etcdctl get --keys-only --prefix /service/demo

Patroni가 etcd에 만들어 둔 클러스터 키들이 /service/demo 아래에 보인다. 1.2에서 이야기한 leader key도 이 중 하나다.

psql 접속

호스트로 돌아와 실행한다.

psql -h localhost -p 5000 -U postgres -W    # 항상 primary로 라우팅
psql -h localhost -p 5001 -U postgres -W    # 정상 standby로 load balance

어느 노드가 primary인지 몰라도 5000 포트로 접속하면 HAProxy가 현재 primary로 이어 준다. SELECT pg_is_in_recovery();를 실행해 보면 5000은 f, 5001은 t를 돌려준다.

failover 관찰 실험

띄운 김에 primary 장애를 흉내 내 보자. 터미널을 두 개 연다. 하나는 Leader가 아닌 Patroni 컨테이너 안에서 상태를 감시하고, 다른 하나에서 Leader 컨테이너를 강제 종료한다. docker stop은 정상 종료 절차를 밟게 하므로, 갑작스러운 장애를 재현하려면 docker kill을 쓴다. 아래는 demo-patroni2가 Leader인 경우다.

# 터미널 1: 상태 감시
docker exec -ti demo-patroni1 bash
patronictl list

# 터미널 2: Leader 컨테이너 강제 종료 (장애 재현)
docker kill demo-patroni2

Leader가 사라지면 leader key 갱신이 멈추고, TTL(기본 30초)이 만료된 뒤 남은 두 member가 leader race를 벌인다. 터미널 1에서 patronictl list를 반복 실행하면 Leader가 다른 member로 넘어가는 과정이 보인다. HAProxy는 health check 실패를 감지하면 기존 연결을 끊도록 구성되어 있어, 5000 포트로 재접속하면 새 primary로 이어진다.

docker start demo-patroni2

정지했던 노드를 다시 시작하면 새 Leader를 따르는 replica로 재합류한다. 승격 순서의 내부 동작과 옛 primary가 복귀할 때의 timeline 처리(pg_rewind)는 Part VI에서 다룬다.

Citus 버전 데모도 있다. docker build -f Dockerfile.citus -t patroni-citus .로 빌드한 뒤 docker compose -f docker-compose-citus.yml up -d로 실행하면 coordinator 3대, worker 4대(2노드 2그룹), etcd 3대, HAProxy 1대 구성이 뜬다. 접속 포트는 동일하게 5000/5001이다.

정리

공식 저장소의 데모는 docker build -t patroni .와 docker compose up -d 두 명령으로 etcd 3, Patroni 3, HAProxy 1 클러스터를 띄운다
상태는 patronictl list로, DCS에 기록된 클러스터 키는 etcdctl get --keys-only --prefix /service/demo로 확인한다
Leader 컨테이너를 강제 종료하면 TTL 만료 뒤 남은 member 중 하나가 승격하고, 복귀한 노드는 replica로 재합류한다

1.3 역사와 생태계