Patroni + etcd + HAProxy 기반 자동 failover 클러스터

자동 failover를 갖춘 PostgreSQL 클러스터를 구축하고 운영합니다. 각 노드의 PostgreSQL은 Patroni가 관리하고, leader 선출은 3(또는 5)개 멤버로 구성된 etcd에서 이루어지며, 애플리케이션은 HAProxy의 쓰기(5000)·읽기(5001) 포트에 선택적으로 keepalived VIP를 통해 접속합니다. 구축 외에도 운영 중인 클러스터를 위한 시나리오가 있습니다: 상태 점검, switchover, 이전 leader 재합류, reinit, 노드 추가/제거, edit-config, pause, Patroni 업그레이드, 전체 중지/기동, etcd 멤버 교체, etcd 과반수 상실. pg-install 가이드는 Patroni 노드에서는 사용하지 않습니다(initdb는 Patroni가 직접 수행합니다). Patroni 없이 failover를 수동으로 수행하는 HA에는 pg-streaming 가이드를 사용하십시오.

구성: PostgreSQL 3대 + etcd 노드(공용 또는 별도) + HAProxy(+ VIP)

시나리오

• 구축: 신규 Patroni 클러스터 — etcd + Patroni + HAProxy(+ VIP) 클러스터를 처음부터 구축합니다. 서버에 PostgreSQL 클러스터가 있으면 안 됩니다. initdb는 Patroni가 수행합니다(pg-install은 적용하지 않습니다).
• 운영 runbook: switchover, failover 테스트, 유지 관리 모드, 파라미터 변경 — 새로 구축한 클러스터에서 기본 작업을 순서대로 시험합니다: 상태 확인, switchover, failover 테스트(leader 중지, 짧은 쓰기 중단), 유지 관리 모드, 파라미터 변경. 유지 관리 시간대에 수행하십시오.
• 클러스터가 정상인가? (상태 점검) — 읽기 전용: 역할, 지연, timeline, REST API, etcd 상태, 슬롯, 대기 중인 재시작 및 유지 관리 모드.
• 계획된 switchover (leader를 다른 노드로 이동) — 유지 관리 전에 leader 역할을 통제된 방식으로 replica에 넘깁니다. 몇 초간 쓰기가 중단되며 데이터 손실은 없습니다.
• Failover 후 이전 leader가 재합류하지 않음 (pg_rewind / reinit) — 장애가 난 이전 leader는 기동되면 replica로 합류해야 합니다. pg_rewind가 실패하면 데이터 디렉터리를 leader로부터 다시 구성합니다.
• replica를 처음부터 다시 구성 (reinit) — replica가 손상되었거나 크게 뒤처졌거나 WAL을 잃은 경우: 데이터 디렉터리를 삭제하고 leader(또는 백업)로부터 다시 구성합니다. leader는 영향을 받지 않습니다.
• 클러스터에 새 노드 추가 — 새 노드를 양식의 목록 끝에 추가하십시오. 소프트웨어가 설치되고, 기존 노드의 pg_hba와 HAProxy가 갱신되며, replica로 합류합니다.
• 클러스터에서 노드 제거 — replica인 노드를 영구적으로 제거합니다. Patroni를 중지하고, DCS 기록과 슬롯을 정리하며, HAProxy에서 제외합니다.
• PostgreSQL 또는 Patroni 설정 변경 (edit-config) — 설정은 DCS에 기록되어 모든 노드에 적용됩니다. 재시작이 필요한 설정은 restart --pending(replica부터)으로 반영합니다.
• 유지 관리를 위해 자동 failover 중지 (pause / resume) — pause 상태에서 Patroni는 PostgreSQL을 건드리지 않고 failover도 하지 않습니다. 네트워크/etcd 유지 관리나 수동 개입 시 사용합니다. 작업이 끝나면 resume합니다.
• Patroni 소프트웨어 업그레이드 (rolling) — 클러스터를 pause 상태로 두고 노드별로 Patroni를 업데이트한 뒤 재시작합니다. PostgreSQL은 중지되지 않고 failover도 발생하지 않습니다.
• 전체 클러스터 중지 / 기동 (올바른 순서) — 계획된 전체 중지(스토리지, 데이터센터 유지 관리): replica 먼저, 다음 leader, 마지막으로 etcd. 기동은 역순입니다.
• etcd 멤버 교체 또는 추가 (etcdctl member) — 손상된 etcd 멤버를 제거하고 새 서버를 추가합니다(또는 멤버 수를 늘립니다). Patroni의 etcd 목록도 갱신합니다.
• etcd 과반수 상실: leader가 읽기 전용이 됨 — etcd quorum이 없으면 Patroni는 leader를 읽기 전용으로 만들고 failover도 일어나지 않습니다. etcd를 복구하거나 단일 멤버에서 다시 구성합니다.

시작하기 전에

• PostgreSQL 노드에 실행 중이거나 이전에 생성된 PostgreSQL 클러스터가 없고 …가 비어 있습니다(클러스터는 Patroni가 직접 생성). 이 서버들에는 pg-install 가이드를 적용하지 않았습니다.
• 모든 서버가 같은 운영체제 버전이고 최신 상태이며, 시간이 NTP로 동기화되어 있습니다(etcd와 Patroni는 시간 오차에 민감합니다).
• PostgreSQL 노드의 RAM은 … GB이고, …는 별도 디스크/LV에 있으며 모든 노드에서 크기가 같습니다.
• etcd 데이터(/var/lib/etcd)가 저지연 디스크(SSD)에 있습니다. 느린 디스크는 leader 선출을 불안정하게 만듭니다. I/O가 많은 PostgreSQL 데이터와 같은 디스크에 두지 않는 것을 권장합니다.
• 주의: etcd 노드 수가 …(짝수)입니다. 짝수는 장애 허용 수를 늘리지 않으므로 3 또는 5를 사용하십시오.
• 서버 간에 다음 포트로 통신할 수 있습니다: PostgreSQL …, Patroni REST 8008, etcd 2379/2380, HAProxy 5000/5001/7000…, VRRP(IP 프로토콜 112)…. 중간 네트워크 장비에도 이 규칙이 열려 있습니다.
• 서버가 PGDG 저장소(download.postgresql.org…, apt.postgresql.org…)와 etcd용 github.com에 HTTPS로 접근할 수 있거나 사내 미러가 설정되어 있습니다.
• VIP …가 비어 있고(어느 서버에서도 사용하지 않음), 네트워크(가상화/클라우드)가 VRRP와 같은 IP의 서버 간 이동을 허용합니다. 클라우드 환경에서는 대개 허용되지 않으므로 대신 클라우드 load balancer를 사용하십시오.
• 주의: VIP용 HAProxy 서버가 1대뿐입니다. 서버가 다운되면 VIP를 옮길 곳이 없습니다.
• 모든 서버에 root 또는 sudo 권한이 있고, 유지 관리 시간대와 롤백 계획이 준비되어 있습니다.
• …: 다른 노드와 같은 운영체제와 PostgreSQL 메이저 버전을 설치할 수 있는 상태이고, …용 디스크가 다른 노드만큼 있으며, 시간이 NTP로 동기화되어 있고, 다른 노드의 …, 8008, etcd 2379에 접근할 수 있습니다.
• … (…): 저지연 디스크(SSD), NTP로 시간 동기화, 다른 etcd 멤버의 2379/2380 및 PostgreSQL 노드에서 2379 접근 허용, github.com 접근 가능 또는 etcd 아카이브가 /tmp에 있음.

가이드 단계

• 준비 (모든 서버) — 서버 이름을 /etc/hosts에 추가 · 시간 동기화(chrony) 활성화 · 커널 설정 및 THP · Firewall 규칙 (PostgreSQL 노드) · Firewall 규칙 (etcd 서버) · Firewall 규칙 (HAProxy 서버)
• etcd 클러스터 — etcd 소프트웨어 설치 · etcd 소프트웨어 설치 · etcd 구성: … · etcd systemd 서비스 생성 · etcd systemd 서비스 생성 · etcd 기동 (모든 etcd 노드에서 동시에) …
• PostgreSQL 및 Patroni 소프트웨어 — PGDG 저장소 추가 · PGDG 저장소 추가 · PostgreSQL 및 Patroni 설치 · 독립 PostgreSQL 서비스 비활성화 및 디렉터리 준비
• Patroni 구성 — 비밀번호를 환경 파일에 기록 · Patroni 서비스에 환경 파일 연결 · patroni.yml: … · 구성 검증
• 클러스터 기동 — 첫 번째 노드에서 Patroni 기동 · 나머지 노드에서 Patroni 기동: … · 클러스터 상태 확인
• HAProxy — HAProxy 설치 · HAProxy 설치 · haproxy.cfg 작성 · haproxy.cfg 작성 · HAProxy 검증 및 기동 · HAProxy 검증 및 기동
• keepalived로 VIP 구성 — keepalived 설치 · keepalived 설치 · keepalived 구성: … · keepalived 기동 · keepalived 기동
• 애플리케이션 사용자 및 연결 테스트 — 애플리케이션 사용자와 데이터베이스 · 애플리케이션 사용자 비밀번호 설정 · REST API health check 엔드포인트 확인 · HAProxy를 통한 연결 시험 · 애플리케이션 연결 문자열
• 구축 후 작업 — etcd snapshot 백업 · etcd snapshot 백업 · 백업 구성 (필수) · 모니터링 연결
• 클러스터 상태 — 멤버, 역할, 지연
• 계획된 switchover — Switchover 수행
• Failover 테스트 (leader 중지) — Leader 노드에서 Patroni 중지 · 새 leader 확인 · 이전 leader 재기동
• 유지 관리 모드 (pause) — 클러스터를 유지 관리 모드로 전환 · 유지 관리 수행 · 유지 관리 모드 해제
• 파라미터 변경 — 클러스터 전체에서 파라미터 변경 · 대기 중인 재시작 적용
• 상태 점검 (읽기 전용) — 멤버, 역할, timeline, 지연 · 최근 leader 변경 (history) · REST API 상태 엔드포인트 · etcd 상태 · 복제 지연, 슬롯, 대기 중인 재시작 (leader에서) · 구성 및 유지 관리 모드
• 계획된 switchover — Switchover 전 점검 · Switchover 수행 · 새 leader와 이전 leader 재합류 확인
• 유지 관리 모드 (pause / resume) — Pause 전 점검 · 클러스터를 유지 관리 모드로 전환 (pause) · 유지 관리 수행 · 유지 관리 모드 해제 (resume)
• Patroni 업그레이드: 준비 — 현재 및 목표 Patroni 버전 · 구성 백업 및 검증 · 클러스터를 유지 관리 모드로 전환 (pause)
• Patroni 업그레이드: 마무리 — 유지 관리 모드 해제 (resume)
• 클러스터 중지 (replica → leader → etcd) — 상태와 역할 기록 · 애플리케이션 중지 · Replica에서 Patroni 중지 · Leader에서 Patroni 중지 · etcd 중지
• 클러스터 기동 (etcd → 마지막 leader → replica) — etcd 기동 (모든 etcd 멤버에서 동시에) · etcd 상태 확인 · 마지막 leader에서 먼저 Patroni 기동 · Replica에서 Patroni 기동 · 클러스터 확인 및 애플리케이션 재개
• 진단: etcd 과반수 상실 — 증상 확인: leader 없음, PostgreSQL 읽기 전용 · etcd 멤버 상태 확인
• 경로 A: etcd 멤버 복구 — 경로 A: etcd 서비스 기동 · Patroni 복구 확인
• 검증 및 예방 조치 — etcd와 Patroni 검증, failsafe 검토