8.1 health check 엔드포인트

Patroni는 노드마다 HTTP REST API 서버를 함께 띄운다. 그중 가장 자주 호출되는 것이 health check 엔드포인트다. 로드밸런서가 어느 노드로 쓰기 트래픽을 보낼지 판별하는 근거가 이 응답이고, Kubernetes probe와 모니터링 에이전트도 같은 주소를 폴링한다. 수신 주소는 restapi.listen으로 지정하며, 공식 예제 구성은 8008 포트를 사용한다.

공통 규약

health check 계열 GET 요청에 Patroni는 노드 상태를 담은 JSON 문서를 HTTP 상태 코드와 함께 반환한다. 판별 조건을 충족하면 200, 아니면 503이다. 응답 코드만 보면 되는 소비자를 위해, JSON body가 필요 없으면 GET 대신 HEAD나 OPTIONS 메서드를 사용해도 된다.

# primary 여부를 상태 코드로만 확인한다
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8008/primary

엔드포인트 전체 표

표에서 먼저 구분해 둘 것이 /primary와 /leader의 차이다. /leader는 DCS의 leader lock을 쥐고 있는지만 확인하고, PostgreSQL이 실제로 primary role로 동작하는지는 확인하지 않는다. 그래서 일반 클러스터의 primary든 standby cluster의 standby leader든 lock 보유자라면 200을 반환한다. 반면 /primary(그리고 /, /read-write)는 leader lock 보유에 더해 PostgreSQL이 primary로 동작 중일 때만 200이다. standby cluster의 leader는 읽기 전용이므로, standby cluster 앞단 라우팅에는 /standby-leader를 쓴다.

/replica 판정 순서

/replica는 세 조건을 모두 통과해야 200을 반환한다. state가 running이어야 하고, role이 replica여야 하며, 해당 노드에 noloadbalance tag가 없어야 한다. ?lag= 파라미터가 붙으면 복제 지연 검사가 추가된다.

    flowchart TD
  REQ["GET /replica"] --> ST{"state = running?"}
  ST -->|아니오| R503["503"]
  ST -->|예| RL{"role = replica?"}
  RL -->|아니오| R503
  RL -->|예| TG{"noloadbalance tag?"}
  TG -->|있음| R503
  TG -->|없음| LG{"?lag= 지정?"}
  LG -->|아니오| R200["200"]
  LG -->|예, 임계 이내| R200
  LG -->|예, 임계 초과| R503
  

noloadbalance tag는 특정 replica를 읽기 분산 대상에서 빼고 싶을 때 쓴다. 백업 전용이나 리포트 쿼리 전용 노드에 이 tag를 붙이면 /replica가 503을 반환해 로드밸런서 pool에서 자연스럽게 빠진다. tag 전반은 Part XII에서 다룬다.

쿼리 파라미터

?lag= 복제 지연 필터

/replica, /asynchronous(/async), /readiness는 ?lag= 파라미터로 허용 복제 지연 상한을 받는다. 값은 바이트 정수 또는 16kB, 64MB, 1GB 같은 human-readable 단위로 쓴다.

curl -s -o /dev/null -w "%{http_code}\n" "http://127.0.0.1:8008/replica?lag=1MB"
curl -s -o /dev/null -w "%{http_code}\n" "http://127.0.0.1:8008/replica?lag=1048576"

lag 계산 기준은 DCS에 기록된 leader의 마지막 WAL 위치(cluster.last_leader_operation)다. 임계를 너무 좁게 잡으면 일시적 지연만으로 replica가 pool에서 들락거리므로, 읽기 용량 변동을 감안해 정한다.

?tag_key=value 사용자 정의 tag 필터

health check 엔드포인트에 ?tag_<key>=<value> 형태로 사용자 정의 tag 조건을 추가하면, 해당 tag가 정의되어 있고 값까지 일치하는 노드만 200을 반환한다. tag가 없거나 값이 다르면 503이다.

# lag 1MB 이내이면서 tag key1=value1 인 replica 만 200
curl -s "http://127.0.0.1:8008/replica?lag=1MB&tag_key1=value1"

단, leader 여부를 확인하는 엔드포인트(/, /primary, /leader, /standby-leader 계열)에서는 사용자 정의 tag 파라미터가 무시된다.

Kubernetes probe 엔드포인트

/liveness와 /readiness는 Kubernetes의 livenessProbe, readinessProbe에 대응하도록 만들어진 엔드포인트다.

/liveness는 Patroni heartbeat loop가 정상 주기로 돌고 있는지만 본다. 마지막 loop 실행이 primary에서 ttl초, replica에서 2*ttl초를 넘겼으면 503을 반환한다. SQL을 실행하지 않는 가벼운 검사다.

/readiness는 노드가 leader이거나, PostgreSQL이 실행 중이고 replication이 붙어 있으며 지연이 임계 이내인 replica면 200을 반환한다. 임계 기본값은 maximum_lag_on_failover이고 ?lag=로 조정한다. ?mode=apply|write는 기준 WAL 위치를 고르는 파라미터로, apply(기본)는 replay된 위치, write는 수신된 위치를 본다.

로드밸런서에서의 사용

공식 저장소가 제공하는 HAProxy 데모 설정은 REST API health check를 그대로 backend 판정에 쓴다. 아래는 그 골격을 두 노드 구성으로 옮긴 예시다.

listen postgres_primary
    bind *:5000
    option httpchk
    http-check expect status 200
    default-server inter 3s fall 3 rise 2 on-marked-down shutdown-sessions
    server node1 10.0.0.11:5432 maxconn 100 check port 8008
    server node2 10.0.0.12:5432 maxconn 100 check port 8008

option httpchk는 기본으로 루트 경로(/)를 검사하므로 leader lock을 가진 primary만 UP으로 판정된다. 읽기 분산 pool은 option httpchk HEAD /replica처럼 check 경로를 바꿔 하나 더 만든다. HAProxy, confd, vip-manager를 포함한 라우팅 구성 전반은 Part IX에서 다룬다.

정리

• health check 엔드포인트는 조건 충족 시 200, 아니면 503을 반환하고 JSON body를 동봉한다. body가 필요 없으면 HEAD나 OPTIONS로 충분하다.
• /leader는 leader lock만, /primary는 lock과 PostgreSQL role을 함께 본다. 읽기 분산은 /replica 계열에 ?lag=, ?tag_key=value 필터를 조합한다.
• /liveness와 /readiness는 Kubernetes probe 대응 엔드포인트로, 각각 heartbeat loop 주기와 replication 상태를 본다.