12. StackGres DB 재기동

소개

SGDbOps의 restart 작업으로 pgsql 클러스터를 재기동한다.

항목	값
Namespace	`db-test`
클러스터	`pgsql`
작업 리소스	`SGDbOps`

1. 재기동 방식

방식	동작	추가 리소스
`InPlace`	기존 인스턴스 재기동	임시 Replica 불필요
`ReducedImpact`	임시 Replica 생성 후 기존 인스턴스 재기동	임시 Replica용 리소스 필요

연결 영향

재기동 중 연결이 끊길 수 있다. 단일 인스턴스의 InPlace 재기동은 서비스 중단이 발생한다.

2. 재기동 전 상태 확인

kubectl get pods -n db-test

kubectl exec -n db-test pgsql-0 -c patroni -- \
  patronictl list

확인 항목:

Primary: Leader / running
Replica: Replica / streaming
Replica의 복제 지연

3. YAML로 재기동

3.1. 전체 인스턴스 재기동

restart-pgsql.yaml 파일을 작성한다.

apiVersion: stackgres.io/v1
kind: SGDbOps
metadata:
  name: restart-pgsql-20261013-1000
  namespace: db-test
spec:
  sgCluster: pgsql
  op: restart
  restart:
    method: InPlace

재기동 작업을 생성한다.

kubectl apply -f restart-pgsql.yaml

작업 이름

새 재기동 작업을 실행할 때는 metadata.name을 변경한다. 완료된 작업에 같은 YAML을 다시 적용해도 새 작업이 생성되지 않는다.

3.2. 재기동 대기 인스턴스만 재기동

설정 변경으로 재기동이 필요한 인스턴스만 처리하려면 onlyPendingRestart: true를 지정한다.

apiVersion: stackgres.io/v1
kind: SGDbOps
metadata:
  name: restart-pgsql-pending-20261013-1000
  namespace: db-test
spec:
  sgCluster: pgsql
  op: restart
  restart:
    method: InPlace
    onlyPendingRestart: true

전체 재기동과 대기 인스턴스 재기동 중 필요한 작업 하나만 실행한다.

3.3. ReducedImpact 사용

추가 리소스가 확보된 환경에서는 재기동 방식을 변경한다.

restart:
  method: ReducedImpact

4. 진행 상태 확인

작업 목록을 확인한다.

kubectl get sgdbops -n db-test

작업 상세 상태를 확인한다.

kubectl get sgdbops restart-pgsql-20261013-1000 \
  -n db-test -o yaml

Pod 상태를 관찰한다.

kubectl get pods -n db-test -w

작업이 진행되지 않으면 이벤트를 확인한다.

kubectl describe sgdbops restart-pgsql-20261013-1000 \
  -n db-test

kubectl get events -n db-test \
  --sort-by=.metadata.creationTimestamp

5. 재기동 후 확인

kubectl exec -n db-test pgsql-0 -c patroni -- \
  patronictl list

확인 항목:

Primary가 Leader / running 상태
Replica가 Replica / streaming 상태
복제 지연 정상
애플리케이션 연결 정상

설정 반영 목적이라면 PostgreSQL에서 실제 값을 확인한다.

SHOW log_min_duration_statement;
SHOW log_checkpoints;

6. Web UI 재기동 오류

6.1. 증상

Web UI의 Restart Cluster 실행 시 이름 검증 오류가 발생했다.

Invalid value: "op2026-10-13-9시 53분 4초":
a lowercase RFC 1123 subdomain must consist of
lower case alphanumeric characters, '-' or '.'

6.2. 원인

Web UI가 작업 이름에 한글과 공백을 포함했다.

op2026-10-13-9시 53분 4초

작업 이름은 다음 규칙을 따라야 한다.

영문 소문자, 숫자, -, . 사용
영문 소문자 또는 숫자로 시작·종료
한글, 공백, 대문자, _ 사용 불가

6.3. 해결

확인 창에 이름 입력란이 없다면 CANCEL로 닫고 YAML로 실행한다.

metadata:
  name: restart-pgsql-20261013-1000
  namespace: db-test

이 오류는 작업 이름 검증 실패이며, DB 재기동 중 발생한 오류와는 구분한다.