4.1 설치

Patroni는 Python 패키지로 배포되는 데몬이라 설치 자체는 단순하다. pip로 직접 설치하는 방법과 배포판 패키지를 쓰는 방법이 있고, 어느 쪽이든 PostgreSQL 바이너리는 별도로 준비한다. Patroni 4.1.4 기준으로 지원하는 PostgreSQL은 9.3부터 18까지고, Python은 3.6 이상이 필요하다(3.14 지원은 4.1.1에서 추가).

pip 설치와 extras

기본 pip install patroni는 Patroni 본체만 설치한다. DCS 클라이언트 라이브러리와 PostgreSQL 드라이버는 필요한 것만 extras로 골라 함께 설치한다.

pip install patroni[psycopg3,etcd3]

extra	용도
`etcd`, `etcd3`	etcd v2 / v3 프로토콜 클라이언트
`consul`	Consul 클라이언트
`zookeeper`, `exhibitor`	ZooKeeper 클라이언트, Exhibitor 연동
`kubernetes`	Kubernetes API를 DCS로 사용
`raft`	내장 Raft, pysyncobj (deprecated)
`psycopg2`, `psycopg2-binary`, `psycopg3`	PostgreSQL 드라이버
`aws`	AWS 환경 연동 의존성
`systemd`	systemd 연동
`jsonlogger`	JSON 형식 로그 출력 (`log.type: json`에 필요)
`all`	전부 포함

PostgreSQL 드라이버는 필수다. psycopg2>=2.5.4, psycopg2-binary, psycopg[binary]>=3.0.0 셋 중 하나가 설치되어 있어야 Patroni가 동작한다. 어떤 DCS 백엔드를 고를지는 Part III에서 다룬다.

배포판 패키지

주요 리눅스 배포판에는 패키지가 준비되어 있다. Debian과 Ubuntu는 patroni 패키지 하나로 설치하고, RHEL 9 이상과 SLES 15는 patroni와 patroni-etcd 두 패키지로 나뉘어 있다. PGDG 저장소(apt.postgresql.org, yum.postgresql.org)에서도 패키지를 제공한다.

# Debian / Ubuntu
sudo apt-get install patroni

# RHEL 9+
sudo dnf install patroni patroni-etcd

설정 파일 생성과 검증

Patroni에는 설정 파일을 만들고 검증하는 도구 세 가지가 들어 있다. patroni.yml을 백지에서 쓸 필요가 없다.

샘플 생성: –generate-sample-config

patroni --generate-sample-config /etc/patroni/patroni.yml

PATRONI_* 환경변수가 설정되어 있으면 그 값을 쓰고, 없으면 기본값 또는 #FIXME 자리표시자를 채운다
postgresql.listen과 postgresql.connect_address는 호스트명으로 얻은 IP에 5432를, restapi 쪽 두 주소는 같은 IP에 8008을 붙인다
postgresql.authentication.rewind 계정은 PostgreSQL 11 이상일 때만 생성한다

실행 중 인스턴스에서 추출: –generate-config

이미 실행 중인 PostgreSQL을 Patroni 관리로 이관할 때는 그 인스턴스의 실제 설정을 읽어 patroni.yml을 만든다. --dsn으로 접속 대상을 지정한다.

patroni --generate-config --dsn "host=127.0.0.1 port=5432 user=postgres" /etc/patroni/patroni.yml

GUC가 patroni.yml의 어느 위치로 가는지는 매핑 규칙이 정해져 있다.

patroni.yml 위치	소스
`scope`	`cluster_name`
`postgresql.listen`	`listen_addresses` + `port`
`postgresql.datadir`	`data_directory`
`postgresql.parameters`	`archive_command`, `restore_command`, `archive_cleanup_command`, `recovery_end_command`, `ssl_passphrase_command`, `hba_file`, `ident_file`, `config_file`
`bootstrap.dcs`	그 외 GUC 전부

pg_hba와 pg_ident 내용은 소스 인스턴스의 실제 파일에서 수집한다.

매핑 규칙을 보면 대부분의 GUC가 bootstrap.dcs로 들어간다. 이 섹션은 클러스터 최초 초기화 때 한 번만 DCS에 기록되는 초기값이라, 생성된 파일을 검토 없이 그대로 쓰기 전에 4.3 구성 3계층의 적용 규칙을 먼저 이해하는 편이 좋다.

검증: –validate-config

작성하거나 생성한 설정 파일은 기동 전에 검증한다.

patroni --validate-config /etc/patroni/patroni.yml

필요하면 --ignore-listen-port(단축 -i), --print(단축 -p) 옵션을 붙인다.

정리

설치는 pip extras 조합 하나 또는 배포판 패키지로 끝나고, PostgreSQL 드라이버(psycopg2 2.5.4 이상 또는 psycopg 3)만 빠뜨리지 않으면 된다. patroni.yml은 --generate-sample-config로 골격을 만들거나 기존 인스턴스에서 --generate-config로 추출한 뒤, --validate-config로 확인하고 다듬는 흐름이 자연스럽다.

4.2 patroni.yml 구조