본문으로 건너뛰기
Docs
Part VII. patronictl
7.1 설정과 상태 조회

7.1 설정과 상태 조회

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

연결 구조

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

    flowchart TD
  CTL["patronictl"]
  DCS["DCS<br/>(etcd, Consul 등)"]
  N1["node1 REST API"]
  N2["node2 REST API"]
  N3["node3 REST API"]
  CTL -->|"상태 조회"| DCS
  CTL -->|"멤버 조작"| N1
  CTL -->|"멤버 조작"| N2
  CTL -->|"멤버 조작"| N3

따라서 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
WindowsC:\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
historyfailover/switchover 이력 표시7.3
versionpatronictl과 멤버들의 버전 표시7.5
show-configdynamic configuration 표시7.2
edit-configdynamic configuration 편집7.2
reload멤버의 로컬 설정 재적용7.2
restart관리 대상 PostgreSQL 재시작7.2
flush예약된 restart/switchover 폐기7.2, 7.3
switchover계획된 leader 교체7.3
failover수동 failover7.3
reinitreplica 데이터 디렉토리 재구축7.3
pause유지보수 모드 진입7.4
resume유지보수 모드 해제7.4
remove클러스터 정보를 DCS에서 삭제7.5
demote-clusterstandby cluster로 전환 (4.1.0+)7.5
promote-clusterstandby 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 표시를 읽으면 클러스터 상태 파악의 대부분이 끝난다.
7.2 구성 변경과 재시작