7.2 구성 변경과 재시작

클러스터 전체에 공통으로 적용되는 dynamic configuration은 DCS에 저장되고, 표준 편집 수단이 patronictl edit-config다. 노드별 로컬 설정(patroni.yml)은 파일을 고친 뒤 reload로 다시 읽게 한다. 두 계층이 어떻게 나뉘고 어느 쪽이 우선하는지는 Part IV에서 다뤘고, 이 장은 변경을 실제로 적용하는 명령들을 본다.

show-config와 edit-config

show-config는 DCS에 저장된 dynamic configuration을 출력한다. edit-config의 읽기 전용 짝이다.

patronictl show-config batman

loop_wait: 10
retry_timeout: 10
ttl: 30
postgresql:
  parameters:
    max_connections: 100

edit-config는 네 가지 방식으로 실행한다.

# Patroni 설정 개별 변경
patronictl edit-config batman -s ttl=20

# PostgreSQL 파라미터 변경 (postgresql.parameters 아래)
patronictl edit-config batman -p max_connections=200

# 파일 기반: 파일 내용을 기존 설정에 반영
patronictl edit-config batman --apply changes.yaml

# 파일 기반: 파일 내용으로 전체 교체
patronictl edit-config batman --replace full-config.yaml

-s/--set은 ttl, loop_wait 같은 Patroni 자체 설정을, -p/--pg는 postgresql.parameters 아래의 PostgreSQL 파라미터를 바꾼다. 변경 확인 프롬프트를 생략하려면 --force를 붙인다(스크립트용).

REST API로도 같은 일을 한다. PATCH /config는 부분 갱신, PUT /config는 전체 덮어쓰기이며, 파라미터 삭제는 값에 null을 지정한다. 상세는 Part VIII 참고.

변경이 전 노드에 퍼지는 과정

edit-config는 DCS의 설정만 바꾼다. 실제 반영은 각 노드의 Patroni가 한다.

    flowchart TD
  E["edit-config 실행"] --> C["DCS의 config 키 갱신"]
  C --> L["각 노드 Patroni가<br/>HA 루프에서 변경 감지"]
  L --> A["로컬에 적용"]
  A --> P{"restart 필요<br/>파라미터인가"}
  P -->|"아니오"| DONE["즉시 반영"]
  P -->|"예"| PR["Pending restart 표시<br/>재시작까지 대기"]
  

각 노드의 Patroni는 HA 루프를 돌 때마다(loop_wait, 기본 10초) DCS를 확인하므로, 변경은 즉시가 아니라 노드마다 다음 루프에서 반영된다. 재시작 없이 적용되는 파라미터는 그 시점에 바로 반영되고, shared_buffers처럼 재시작이 필요한 파라미터는 값만 바뀐 채 pending restart 플래그가 붙는다.

reload: 로컬 설정 재적용

dynamic configuration이 아니라 노드의 patroni.yml을 고쳤다면, 그 파일을 다시 읽게 하는 명령이 reload다.

patronictl reload batman node2               # 특정 멤버
patronictl reload batman -r replica --force  # replica 전체

--role 필터는 leader, primary, replica, any를 받는다. REST로는 POST /reload가 같은 동작이다. reload는 설정 파일을 다시 읽어 적용하는 데까지만 수행하고 PostgreSQL 재시작은 하지 않으므로, 재시작이 필요한 파라미터는 여전히 별도의 restart 대상으로 남는다.

pending restart가 붙는 조건과 해소

재시작이 필요한 PostgreSQL 파라미터를 dynamic configuration으로 바꾸면, Patroni는 영향을 받는 멤버에 pending restart 플래그를 붙인다. 공식 FAQ는 언제 어떻게 재시작할지는 사용자가 결정할 몫이라고 설명한다. Patroni가 알아서 재시작하지 않는다는 뜻이다.

플래그와 사유는 patronictl list로 확인한다.

patronictl list batman -e     # Pending restart reason 컬럼까지 표시

플래그는 해당 멤버의 PostgreSQL을 재시작해야 사라진다. 재시작 수단은 patronictl restart 또는 POST /restart다.

restart 옵션 상세

patronictl restart batman node2 --force            # 특정 멤버만
patronictl restart batman --pending --force        # pending restart 멤버만
patronictl restart batman --pg-version 16.3        # 16.3보다 오래된 버전만
patronictl restart batman -r replica               # replica 만
patronictl restart batman --any                    # 조건에 맞는 멤버 중 1대만
patronictl restart batman --timeout 60             # 60초 초과 시 중단
patronictl restart batman --scheduled 2026-08-05T03:00+09:00   # 예약
patronictl flush batman restart                    # 예약 취소

• --pending: pending restart 플래그가 붙은 멤버만 선택한다. 설정 변경 후 필요한 노드만 골라 재시작하는 가장 안전한 필터
• --pg-version: 관리 중인 PostgreSQL 버전이 지정값보다 오래된 멤버만 선택한다. minor 업그레이드로 바이너리를 교체한 뒤 아직 구버전으로 도는 노드만 재시작할 때 쓴다
• --scheduled: 지정 시각에 예약 재시작한다. now도 지정 가능하다. 예약을 취소하려면 patronictl flush CLUSTER restart를 실행한다
• --any: 조건에 맞는 멤버 중 임의의 1대만 재시작한다
• --timeout: 지정 시간을 초과하면 재시작을 중단한다
• -r/--role: role로 대상을 거른다

전 멤버를 한 번에 재시작하는 대신 replica부터 하나씩 재시작하고 leader를 마지막에 처리하는 rolling restart 순서가 일반적인 관행이다. --pg-version 필터도 이 시나리오를 위해 존재한다.

정리

dynamic configuration 변경은 edit-config로 DCS를 바꾸면 각 노드가 다음 HA 루프에서 받아 적용하는 흐름이고, 로컬 patroni.yml 변경은 reload로 다시 읽게 한다. 재시작이 필요한 파라미터는 pending restart 플래그로 표시만 될 뿐 Patroni가 알아서 재시작하지 않으므로, patronictl restart --pending으로 대상을 좁혀 마무리하는 것까지가 DBA의 일이다.