7.1 설정과 상태 조회

patronictl은 Patroni 클러스터를 조회하고 조작하는 표준 CLI 도구다. Patroni 데몬과 같은 설정 파일 형식을 공유하므로 데몬용 patroni.yml을 그대로 지정해 실행해도 동작한다. 이 장에서는 patronictl이 어디에 연결되어 동작하는지, 설정을 어디서 읽는지, 그리고 가장 자주 실행하는 patronictl list 출력을 읽는 법을 다룬다.

연결 구조

patronictl은 한 곳에만 연결되는 도구가 아니다. 클러스터 상태 조회는 DCS(Distributed Configuration Store)에서 읽고, 멤버 개별 조작(restart, reload, reinit 등)은 해당 멤버의 REST API를 호출해 수행한다.

따라서 patronictl을 실행하는 위치에서 DCS와 각 멤버의 REST API 양쪽에 네트워크로 닿아야 한다. list처럼 DCS만 읽는 명령은 REST API가 막혀 있어도 동작하지만, restart 같은 조작 명령은 실패한다.

설정 소스

patronictl이 참조하는 설정 섹션은 세 가지다.

ctl:                              # patronictl 전용 REST API 클라이언트 설정
  authentication:
    username: admin
    password: strong-password
  cacert: /etc/patroni/ca.pem     # 서버 인증서 검증용 CA 번들
  # insecure: true                # 서버 인증서 검증 생략

restapi:                          # ctl 에 값이 없으면 여기로 fallback
  authentication:
    username: admin
    password: strong-password

ctl: REST API 접근에 쓸 Basic-auth 인증 정보와 서버 신원 검증 방법. 클라이언트 인증서(mTLS)를 쓰면 certfile, keyfile, keyfile_password를 지정한다
restapi: ctl에 인증 정보가 없을 때 restapi.authentication 값을 fallback으로 사용한다
DCS 섹션(etcd3 등): DCS 접속과 인증 정보. 백엔드별 키는 Part III 참고

설정 파일은 -c/--config-file 옵션이나 환경 변수 PATRONICTL_CONFIG_FILE로 지정한다. 지정하지 않으면 OS별 기본 경로에서 patronictl.yaml을 찾는다.

OS	기본 탐색 경로
Unix/Linux	`~/.config/patroni`
macOS	`~/Library/Application Support/patroni`
Windows	`C:\Users\<user>\AppData\Roaming\patroni`

설정 파일 없이 DCS 주소만 직접 지정하는 방법도 있다. -d/--dcs-url의 형식은 DCS://HOST:PORT/NAMESPACE다.

patronictl -d etcd3://10.0.0.11:2379/service list batman

REST API가 자체 서명 인증서를 쓰는 환경에서는 -k/--insecure로 서버 인증서 검증을 생략한다.

patronictl list 출력 해석

patronictl -c /etc/patroni/patroni.yml list batman

+ Cluster: batman (7027673783600665556) -------+----+-------------+-----+------------+-----+
| Member | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+--------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| node1  | 10.0.0.11:5432 | Leader  | running   |  2 |             |     |            |     |
| node2  | 10.0.0.12:5432 | Replica | streaming |  2 | 0/4000060   |   0 | 0/4000060  |   0 |
| node3  | 10.0.0.13:5432 | Replica | streaming |  2 | 0/4000060   |   0 | 0/4000060  |   0 |
+--------+----------------+---------+-----------+----+-------------+-----+------------+-----+

헤더에는 클러스터 이름과 함께 PostgreSQL의 system identifier가 표시된다. 멤버들이 같은 system identifier를 공유하는지, 즉 정말 한 클러스터에서 갈라져 나온 인스턴스들인지 확인하는 단서가 된다.

컬럼별 의미는 다음과 같다.

Member: Patroni 멤버 이름
Host: 멤버의 위치 (호스트:포트)
Role: 현재 role. 값은 네 가지로, Leader(leader lock을 가진 primary), Standby Leader(standby cluster의 leader), Sync Standby(synchronous replica), Replica(일반 replica)
State: 그 멤버 PostgreSQL의 현재 상태. running, streaming, in archive recovery, stopped, crashed 다섯 값이다. 정상 streaming 복제 중인 replica는 streaming, restore_command로 WAL을 복원하며 도는 노드는 in archive recovery로 표시된다
TL: 현재 PostgreSQL timeline. 전환이 일어날 때마다 증가하므로, 멤버 간 TL이 다르면 어떤 노드가 새 timeline을 못 따라왔다는 신호다
Receive LSN / Lag: 수신되어 디스크에 sync된 마지막 WAL 위치와 upstream 대비 lag(MB)
Replay LSN / Lag: recovery 중 replay된 마지막 WAL 위치와 lag(MB)

설정 변경으로 재시작이 필요해진 멤버는 Pending restart 컬럼에 *가 붙는다. 빈 값이면 재시작이 필요 없다는 뜻이다. 이 플래그가 붙는 조건과 해소는 7.2에서 다룬다.

확장 컬럼과 출력 포맷

-e/--extended를 붙이면 Pending restart, Pending restart reason, Scheduled restart, Tags 컬럼을 값이 비어 있어도 강제로 표시한다. 재시작이 왜 필요한지, 어떤 tag가 걸려 있는지 확인할 때 쓴다.

출력 포맷은 -f/--format으로 바꾼다. pretty(기본 표), tsv, json, yaml 네 가지다. 모니터링 스크립트에서 파싱할 때는 json이 무난하다.

patronictl list batman -e            # 확장 컬럼 표시
patronictl list batman -f json       # JSON 출력

watch 모드

-W는 2초 간격으로 화면을 갱신하며 감시하고, -w/--watch TIME은 갱신 주기를 직접 지정한다. switchover나 restart 진행 상황을 지켜볼 때 유용하다.

patronictl list batman -w 5          # 5초 간격으로 갱신

topology: replication 트리

topology는 list의 트리 버전이다. 같은 정보를 멤버 간 replication 관계에 따라 들여쓰기한 트리로 보여준다. replicatefrom tag로 cascading replication을 구성했다면 어떤 replica가 어느 노드에서 복제받는지 이 명령으로 확인한다. -W/-w watch 옵션도 동일하게 지원한다.

patronictl topology batman

서브커맨드 한눈 보기

4.1.4 기준 서브커맨드는 19개다. Citus 클러스터에서는 다수 명령이 --group CITUS_GROUP 옵션을 추가로 받는다.

서브커맨드	역할	상세
`list`	멤버 상태 표 출력	이 장
`topology`	멤버를 replication 트리로 표시	이 장
`dsn`	멤버 접속 문자열 출력	7.5
`query`	멤버에 SQL 실행	7.5
`history`	failover/switchover 이력 표시	7.3
`version`	patronictl과 멤버들의 버전 표시	7.5
`show-config`	dynamic configuration 표시	7.2
`edit-config`	dynamic configuration 편집	7.2
`reload`	멤버의 로컬 설정 재적용	7.2
`restart`	관리 대상 PostgreSQL 재시작	7.2
`flush`	예약된 restart/switchover 폐기	7.2, 7.3
`switchover`	계획된 leader 교체	7.3
`failover`	수동 failover	7.3
`reinit`	replica 데이터 디렉토리 재구축	7.3
`pause`	유지보수 모드 진입	7.4
`resume`	유지보수 모드 해제	7.4
`remove`	클러스터 정보를 DCS에서 삭제	7.5
`demote-cluster`	standby cluster로 전환 (4.1.0+)	7.5
`promote-cluster`	standby cluster를 승격 (4.1.0+)	7.5

정리

patronictl은 조회는 DCS에서, 멤버 조작은 REST API로 수행한다. 양쪽 모두에 닿는 위치에서 실행해야 한다.
인증 정보는 ctl 섹션에서 읽고, 없으면 restapi.authentication으로 fallback한다. 설정 파일은 -c, PATRONICTL_CONFIG_FILE, OS별 기본 경로 순으로 찾는다.
list의 Role 네 값과 State 다섯 값, TL, Lag, Pending restart 표시를 읽으면 클러스터 상태 파악의 대부분이 끝난다.

연결 구조​

설정 소스​

patronictl list 출력 해석​

확장 컬럼과 출력 포맷​

watch 모드​

topology: replication 트리​

서브커맨드 한눈 보기​

정리​