본문으로 건너뛰기

4.5 기존 인스턴스 인수

이미 운영 중인 PostgreSQL에 자동 failover를 구성하려는 경우가 많습니다. pg_autoctl create postgres는 --pgdata가 기존 데이터 디렉터리를 가리키면 initdb를 생략하고 해당 인스턴스를 등록합니다. 다만 이 기능은 모든 HA 구성을 그대로 이전하는 마이그레이션 도구가 아닙니다. 조건이 맞을 때만 동작합니다. 이 노트에서는 이 경로를 실습하지 않았습니다. 아래 내용은 v2.2 pg_autoctl create postgres 문서와 운영 문서를 근거로 합니다.

두 가지 인수 경로​

모드 2: 기존 primary 등록​

PGDATA가 PostgreSQL 인스턴스에 속하면 pg_autoctl은 이 노드를 monitor에 "tentative SINGLE" 상태로 등록합니다. 대상 --formation과 group이 비어 있을 때만 monitor가 등록을 허용합니다. 이후 pg_autoctl이 기존 서버를 pg_auto_failover용으로 준비합니다. 운영 문서도 PostgreSQL이 실행 중이면 새 노드를 SINGLE로 등록한다고 설명합니다. 이때 monitor의 역할 배정 정책은 적용하지 않습니다.

그다음 standby는 일반적인 방식으로 추가합니다. 빈 PGDATA로 create postgres를 실행하면 pg_basebackup으로 standby가 만들어집니다.

모드 4: 기존 standby 합류​

group에 이미 노드가 있고 기존 PGDATA의 PostgreSQL이 멈춰 있어야 합니다. 또한 system identifier가 해당 노드들과 같아야 합니다. 이 조건을 충족하면 pg_autoctl은 이 디렉터리를 standby로 설정합니다. primary_conninfo를 현재 primary로 바꾸고 PostgreSQL을 시작합니다. v2.2는 실행 중인 기존 standby를 지원하지 않으므로 실패합니다(keeper_pg_init.c). 또한 system identifier 일치는 등록 조건일 뿐입니다. 이 경로는 pg_basebackup과 pg_rewind를 모두 생략합니다. 따라서 해당 PGDATA가 현재 primary의 timeline을 따라갈 수 있는지 따로 확인해야 합니다. 필요한 WAL이 남아 있는지도 확인해야 합니다.

# system identifier 비교
pg_controldata "$PGDATA" | grep 'Database system identifier'

사전 점검 목록​

문서가 보장하는 범위는 위 판정까지입니다. 운영 중인 인스턴스를 인수하기 전에는 다음 사항을 직접 확인해야 합니다.

  • 최근 전체 백업과 WAL 아카이브 복구 가능 여부
  • 기존 HA 도구(repmgr, Patroni 등)의 데몬 중지와 자동 재기동 해제
  • systemd 등 다른 서비스 관리자가 같은 PGDATA를 실행하지 않도록 비활성화
  • postgresql.conf에 있는 기존 synchronous_standby_names, primary_conninfo, primary_slot_name 설정
  • 기존 replication slot 목록과 불필요한 slot 정리
  • listen_addresses, port, SSL 인증서 경로
  • wal_log_hints 또는 data checksums 상태 (pg_rewind 사용 조건)
  • pg_hba.conf의 기존 규칙과 --skip-pg-hba 여부

마지막 항목이 중요합니다. pg_autoctl은 postgresql.conf 맨 위에 include를 추가하여 postgresql-auto-failover.conf를 읽습니다(4.3). 기존 postgresql.conf 아래쪽에 같은 항목이 있으면 나중에 정의한 값이 우선합니다. 따라서 기존 설정이 pg_auto_failover에서 관리하려는 synchronous_standby_names 같은 값을 덮어쓸 수 있습니다.

경고

wal_log_hints는 재시작이 필요한 설정입니다. 기존 인스턴스를 인수할 때 postgresql-auto-failover.conf의 여러 값을 반영해야 할 수 있습니다. 해당 값에는 wal_log_hints, max_wal_senders, shared_preload_libraries 등이 있습니다. 이 경우 PostgreSQL 재시작이 필요할 가능성이 있습니다. 실습하지 않았으므로 재시작 여부와 시점을 스테이징에서 확인한 뒤 작업 시간을 정해야 합니다.

예시 명령​

# 기존 primary (formation default, group 0이 비어 있어야 함)
export PGDATA=/var/lib/postgresql/17/main
pg_autoctl create postgres \
  --pgdata "$PGDATA" \
  --name db-a --hostname db-a.example.internal \
  --monitor 'postgres://autoctl_node@monitor.example.internal/pg_auto_failover?sslmode=require' \
  --auth scram-sha-256 --ssl-self-signed

pg_autoctl show systemd --pgdata "$PGDATA" | sudo tee /etc/systemd/system/pgautofailover.service
sudo systemctl daemon-reload && sudo systemctl enable --now pgautofailover

--run을 추가하지 않고 먼저 등록만 한 뒤 systemd로 서비스를 시작하는 방식입니다. 등록 결과는 monitor에서 pg_autoctl show state로 확인합니다.

노트

v2.2 FAQ는 상태 머신이 복구할 수 없는 상황에 대응하는 방법을 소개합니다. 노드를 drop node로 제외한 뒤 create postgres로 다시 등록하는 방법입니다. 이때도 같은 원리가 적용됩니다. 명령은 PostgreSQL이 이미 실행 중임을 감지하고 중단된 지점부터 계속 진행합니다. 경우에 따라 로컬 상태 파일을 삭제해야 한다는 안내가 오류 메시지에 표시된다고 문서는 설명합니다.

정리​

기존 PGDATA 인수는 두 경우에 동작합니다. 비어 있는 group에 기존 primary를 tentative single로 등록하는 경우와 같은 system identifier를 가진 기존 standby를 합류시키는 경우입니다. 이미 여러 노드로 운영 중인 다른 HA 구성을 한 번에 이전하는 기능은 아닙니다. 먼저 백업 상태와 기존 HA 데몬 중지 여부를 확인하고 설정 충돌을 점검합니다. 재시작 여부는 스테이징에서 확인합니다.