4.2 patroni.yml 구조

Patroni 데몬은 기동할 때 설정 파일 하나를 읽는다. 관례상 patroni.yml이라 부르는 이 파일에 노드의 신원, DCS 접속 정보, PostgreSQL 인스턴스 관리 방법, REST API 설정이 전부 들어간다. 파일이 길어 보여도 골격은 최상위 키 세 개와 아홉 갈래 섹션으로 정리된다.

신원을 정하는 최상위 키

• scope: 클러스터 이름이다. DCS 키 경로에 들어가고 PostgreSQL의 cluster_name 파라미터로도 쓰인다. 한 클러스터의 모든 노드가 같은 값을 갖는다.
• namespace: DCS 안에서 Patroni가 키를 만드는 경로의 접두다. 기본값은 /service로, 이 경우 클러스터의 키들이 /service/<scope>/ 아래에 생긴다.
• name: 노드 이름이다. 클러스터 안에서 유일해야 한다.

섹션 지도

동작하는 최소 예시

etcd 3대를 etcd3 프로토콜로 쓰는 3노드 클러스터의 첫 노드 기준이다.

scope: demo
namespace: /service
name: node1

etcd3:
  hosts: 10.0.0.11:2379,10.0.0.12:2379,10.0.0.13:2379

restapi:
  listen: 0.0.0.0:8008
  connect_address: 10.0.0.21:8008

bootstrap:
  dcs:
    ttl: 30
    loop_wait: 10
    retry_timeout: 10
    postgresql:
      use_pg_rewind: true

postgresql:
  listen: 0.0.0.0:5432
  connect_address: 10.0.0.21:5432
  data_dir: /var/lib/postgresql/17/main
  bin_dir: /usr/lib/postgresql/17/bin
  authentication:
    superuser:
      username: postgres
      password: strong-password
    replication:
      username: replicator
      password: strong-password
    rewind:
      username: rewind_user
      password: strong-password
  parameters:
    shared_buffers: 1GB
  pg_hba:
    - host all all 10.0.0.0/24 scram-sha-256
    - host replication replicator 10.0.0.0/24 scram-sha-256

나머지 노드는 name과 두 connect_address만 자기 주소로 바꾸면 된다. bootstrap.dcs 아래 값은 클러스터를 처음 만드는 순간 한 번만 DCS에 기록되고 이후에는 파일을 고쳐도 반영되지 않는데, 이 동작은 4.3에서 다룬다.

postgresql 섹션의 주요 키

listen과 connect_address는 용도가 다르다. listen은 PostgreSQL이 bind할 주소로, 쉼표로 여러 주소를 적되 port는 마지막에 한 번만 붙인다(127.0.0.1,10.0.0.21:5432). Patroni는 이 목록의 첫 주소로 로컬 접속한다. connect_address는 다른 노드와 애플리케이션이 실제로 접근하는 주소다.

접속 계정은 authentication 아래 세 벌을 정의한다. superuser는 Patroni가 인스턴스를 관리할 때 쓰는 계정으로 initdb 시점에 만들어진다. replication은 streaming replication용이다. rewind는 선택 사항으로, PostgreSQL 11 이상에서 초기화 때 생성되고 pg_rewind 실행에 필요한 함수들의 EXECUTE 권한을 자동으로 받는다.

data_dir는 PGDATA 위치다. 기존 디렉토리를 가리키거나, 없으면 bootstrap 과정에서 Patroni가 초기화한다. bin_dir는 PostgreSQL 바이너리 경로로, 비워 두면 PATH에서 찾는다.

parameters는 GUC를 dict로 적는다. 다만 max_connections처럼 Patroni가 강제 제어하는 파라미터는 여기 적어도 무시된다(4.4).

pg_hba는 pg_hba.conf를 생성할 라인 목록이다. replication 계정이 다른 노드에서 접속할 라인이 반드시 포함되어야 한다.

callbacks는 상태 변화 시 실행할 스크립트를 지정한다. on_start, on_stop, on_restart, on_reload, on_role_change 다섯 지점이 있고, 스크립트는 action, role, 클러스터 이름을 인자로 받는다. role 변화에 맞춰 DNS나 VIP를 옮기는 식의 연결 라우팅에 흔히 쓰이는데, 구체적인 활용은 Part IX에서 다룬다.

create_replica_methods는 replica를 만들 방법의 우선순위 목록이다. 기본값은 basebackup이며, pgBackRest 같은 백업 도구로 replica를 만들려면 여기에 custom method를 추가한다(Part V).

restapi 섹션

REST API는 HAProxy 같은 외부 도구의 health check 대상이자 Patroni 노드 사이의 통신 창구다. listen은 REST API 서버가 bind할 주소다. connect_address는 클러스터의 다른 모든 멤버가 접근할 주소로, DCS의 member 키에 기록되고 leader race 중 어느 노드의 WAL이 가장 앞서 있는지 확인하는 통신에 쓰인다.

정리

• patroni.yml의 골격은 신원 키 3개(scope, namespace, name)와 아홉 갈래 섹션이다
• listen은 bind 주소, connect_address는 바깥에서 접근하는 주소다. postgresql과 restapi 양쪽 모두 이 구분이 있다
• 접속 계정은 superuser, replication, rewind 세 벌을 정의하고 bootstrap 시점에 생성된다
• bootstrap.dcs는 최초 초기화 때 한 번만 DCS에 기록된다