4.1 패키지 설치

pg_auto_failover는 PostgreSQL 커뮤니티 패키지 저장소(PGDG)에서 배포합니다. Debian 계열은 패키지를 역할에 따라 둘로 나눕니다. RPM 계열은 하나의 패키지로 제공합니다. 두 계열 모두 PostgreSQL 서버 패키지를 먼저 설치해야 합니다. pg_autoctl이 같은 머신에 있는 pg_ctl, initdb, pg_basebackup, pg_rewind를 호출하기 때문입니다.

패키지 구성

배포판	패키지	내용	필요한 노드
Debian, Ubuntu	`pg-auto-failover-cli`	`pg_autoctl` 명령	모든 노드
Debian, Ubuntu	`postgresql-17-auto-failover`	monitor용 `pgautofailover` extension (PostgreSQL 17용)	monitor
RHEL, Rocky, Fedora	`pg_auto_failover`	`pg_autoctl`과 extension을 함께 포함	모든 노드

Debian 계열의 extension 패키지 이름에는 PostgreSQL major 버전이 포함됩니다. monitor를 PostgreSQL 16으로 운영한다면 postgresql-16-auto-failover를 설치합니다. 데이터 노드에는 extension이 필요하지 않습니다. 다만 실습 이미지처럼 모든 노드에 같은 이미지를 사용한다면 두 패키지를 함께 포함하는 편이 관리하기 쉽습니다.

Debian과 Ubuntu

Debian의 postgresql-17 패키지는 설치 과정에서 main 클러스터를 initdb하고 systemd 서비스로 등록합니다. pg_auto_failover를 사용할 때는 이 기본 클러스터가 방해됩니다. pg_autoctl이 PGDATA를 직접 생성하고 PostgreSQL을 자식 프로세스로 실행하기 때문입니다. v2.2 설치 문서는 서버 패키지를 설치하기 전에 create_main_cluster = false를 설정하도록 안내합니다.

# PGDG 저장소 등록 (v2.2 문서의 예시, 배포판 코드명은 환경에 맞춘다)
curl https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add -
echo "deb http://apt.postgresql.org/pub/repos/apt bookworm-pgdg main" \
  > /etc/apt/sources.list.d/pgdg.list

# 기본 main 클러스터 생성을 막는다
echo 'create_main_cluster = false' | sudo tee -a /etc/postgresql-common/createcluster.conf
apt-get update
apt-get install -y --no-install-recommends postgresql-17

# pg_auto_failover
sudo apt-get install pg-auto-failover-cli
sudo apt-get install postgresql-17-auto-failover   # monitor 노드

노트

apt-key는 최신 Debian과 Ubuntu에서 사용 중단 경고를 표시합니다. 위 명령은 v2.2 문서의 예시를 옮긴 것입니다. 실제로 저장소를 등록할 때는 PostgreSQL wiki의 Apt 안내를 따르는 편이 안전합니다.

실습에서는 공식 postgres:17 이미지(Debian 13 trixie)를 사용했습니다. 이 이미지에는 PGDG 저장소가 이미 등록되어 있습니다. 설치하기 전에 후보 버전을 확인했습니다.

docker run --rm postgres:17 bash -c \
  'apt-get update -qq >/dev/null; apt-cache policy pg-auto-failover-cli'

pg-auto-failover-cli:
  Installed: (none)
  Candidate: 2.2-4.pgdg13+1
  Version table:
     2.2-4.pgdg13+1 500
        500 http://apt.postgresql.org/pub/repos/apt trixie-pgdg/main arm64 Packages
     2.2-3.pgdg13+1 500
        500 http://apt.postgresql.org/pub/repos/apt trixie-pgdg/main arm64 Packages
     2.2-2 500
        500 http://deb.debian.org/debian trixie/main arm64 Packages

같은 버전은 Debian 공식 저장소에도 2.2-2로 제공됩니다. PGDG의 리비전(-4)이 더 높습니다. 따라서 PGDG 저장소가 등록된 환경에서는 PGDG 패키지를 선택합니다. 설치 후에는 pg_autoctl --version으로 버전을 확인합니다.

pg_autoctl version 2.2-4.pgdg13+1
pg_autoctl extension version 2.2
compiled with PostgreSQL 18.4 (Debian 18.4-1.pgdg13+1) on aarch64-unknown-linux-gnu, compiled by gcc (Debian 14.2.0-19) 14.2.0, 64-bit
compatible with Postgres 13, 14, 15, 16 and 17

compiled with PostgreSQL 18.4는 pg_autoctl 바이너리를 빌드할 때 사용한 libpq 버전입니다. 관리 대상인 PostgreSQL 버전과는 무관합니다. 실제 지원 범위는 마지막 줄의 호환 목록입니다.

PostgreSQL 18 패키지

postgres:18 이미지에서도 postgresql-18-auto-failover의 후보 버전은 2.2-4.pgdg13+1이었습니다. 패키지는 존재하지만 v2.2 릴리스는 PostgreSQL 18 호환성을 선언하지 않았습니다. 위 --version 출력의 호환 목록에도 18이 없습니다. 이 노트에서는 PostgreSQL 18 조합을 실습하지 않았습니다. PostgreSQL 18 지원은 main 브랜치(#1144)에 반영되었으며 아직 릴리스되지 않았습니다(1.3).

RHEL 계열

v2.2 문서에 따르면 RPM 계열은 yum.postgresql.org 저장소의 pg_auto_failover 패키지 하나에 pg_autoctl과 extension을 함께 포함합니다. 이 노트에서는 RPM 패키지를 설치하지 않았습니다. 따라서 패키지 이름의 버전 접미사와 설치 경로는 저장소에서 직접 확인해야 합니다.

경고

반드시 같은 저장소를 사용할 필요는 없습니다. 하지만 선택한 PostgreSQL major에 맞는 pg_ctl을 사용해야 합니다. monitor extension 패키지의 버전도 일치시켜야 합니다. PGDG 저장소 한 곳에서 받으면 이 조합을 맞추기 쉽습니다. pg_autoctl은 PATH에서 pg_ctl을 찾습니다. PATH에 여러 버전의 pg_ctl이 있으면 --pgctl로 경로를 지정하라는 메시지를 표시합니다. Debian에서는 /usr/lib/postgresql/17/bin/pg_ctl, RPM에서는 /usr/pgsql-17/bin/pg_ctl 형태입니다.

컨테이너 이미지로 만들 때

실습의 Dockerfile은 위 과정을 이미지 하나에 담았습니다. 공식 postgres 이미지는 기본 클러스터를 생성하지 않습니다. 따라서 create_main_cluster 설정이 필요하지 않습니다. pg_autoctl이 호출하는 initdb, pg_ctl, postgres는 root 실행을 허용하지 않습니다. 따라서 이미지 마지막에 USER postgres를 둡니다.

ARG PG_MAJOR=17
FROM postgres:${PG_MAJOR}
ARG PG_MAJOR
RUN apt-get update \
 && apt-get install -y --no-install-recommends \
      postgresql-${PG_MAJOR}-auto-failover \
      pg-auto-failover-cli \
      iproute2 procps \
 && rm -rf /var/lib/apt/lists/*
RUN mkdir -p /var/lib/pgaf && chown postgres:postgres /var/lib/pgaf
USER postgres
ENV PATH=/usr/lib/postgresql/${PG_MAJOR}/bin:$PATH \
    PGDATA=/var/lib/pgaf/data \
    XDG_CONFIG_HOME=/var/lib/pgaf/config \
    XDG_DATA_HOME=/var/lib/pgaf/share

XDG_CONFIG_HOME과 XDG_DATA_HOME을 볼륨 안으로 옮긴 이유는 4.4에서 설명합니다. 두 경로가 컨테이너 레이어에 남아 있으면 컨테이너를 다시 만들 때 keeper 상태 파일이 사라집니다.

정리

Debian 계열은 모든 노드에 pg-auto-failover-cli를 설치합니다. monitor에는 postgresql-NN-auto-failover도 추가로 설치합니다. 서버 패키지가 기본 클러스터를 만들지 않도록 미리 설정합니다. 2026-09 기준 PGDG가 제공하는 버전은 2.2입니다. 공식 호환 범위는 PostgreSQL 13~17입니다.

패키지 구성​

Debian과 Ubuntu​

PostgreSQL 18 패키지​

RHEL 계열​

컨테이너 이미지로 만들 때​

정리​

패키지 구성

Debian과 Ubuntu

PostgreSQL 18 패키지

RHEL 계열

컨테이너 이미지로 만들 때

정리