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로 확인하고 다듬는 흐름이 자연스럽습니다.