Barman Cloud로 백업 구성하기

내용 검토: 2026. 09. 28.

결론부터

백업 저장소 연결, 연속 WAL 보관, 주기적 베이스 백업을 각각 구성하고 함께 확인한다.

“S3 주소를 넣었다”는 것과 “특정 시점까지 복구할 수 있다”는 것은 다르다. 베이스 백업을 만들고 이후 WAL이 끊기지 않게 보관해야 PITR이 가능하다.

이 장에서 처음 나오는 말3개

CNPG-ICloudNativePG Interface: 백업 같은 기능을 플러그인으로 연결하는 인터페이스.
Barman Cloud 플러그인: CNPG와 오브젝트 스토리지 사이의 물리 백업·WAL 보관·복구를 연결한다.
ObjectStore: 플러그인이 사용할 저장소 위치·자격증명 참조·보관 정책을 선언하는 리소스.

기존 온프렘 예제와의 차이

기존 온프렘 페이지에는 spec.backup.barmanObjectStore 방식이 있다. 내장 방식은 CNPG 1.26부터 deprecated되었으며 이 덱은 플러그인 방식을 기준으로 한다. 기존 운영 클러스터의 설정을 단순 삭제하고 새 필드만 붙이는 방식으로 이행하지 않는다. 기존 백업 위치·serverName·WAL 이력을 보존하는 공식 이행 절차를 확인한다. (백업 방식, 내장 방식에서 이행)

준비 조건

이 예제는 CNPG Cluster의 study-pg를 사용한다. YAML은 문서 대조용 예제이며 실제 백업 환경에서의 실행 확인은 별도로 필요하다.

플러그인 설치 문서에서 CNPG 호환성·cert-manager 등 의존성을 확인한다. 플러그인은 CNPG operator와 같은 namespace에 설치한다.
ObjectStore와 자격증명 Secret은 DB가 있는 pg-study namespace에 준비한다.
실습 전용 버킷과 빈 저장 경로, 접근 권한·DNS·네트워크·TLS 신뢰를 확인한다.
Secret pg-study-s3에는 ACCESS_KEY_ID·ACCESS_SECRET_KEY, 사내 CA용 Secret pg-study-s3-ca에는 ca.crt 키를 준비한다. 실제 값은 비밀 관리 절차로 생성한다.

AWS S3처럼 별도 endpoint나 사내 CA가 필요 없는 환경은 해당 필드를 제거하고 제공자별 인증 방식에 맞춘다. 아래는 S3 호환 저장소와 사내 CA를 사용하는 예다. (스토리지 제공자 설정)

저장소 정의

object-store.yaml로 저장하고 예시 주소·버킷·Secret 참조를 실제 실습 자원으로 바꾼다.

apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
  name: study-backups
  namespace: pg-study
spec:
  configuration:
    destinationPath: s3://pg-study-backups/
    endpointURL: https://s3.example.internal
    endpointCA:
      name: pg-study-s3-ca
      key: ca.crt
    s3Credentials:
      accessKeyId:
        name: pg-study-s3
        key: ACCESS_KEY_ID
      secretAccessKey:
        name: pg-study-s3
        key: ACCESS_SECRET_KEY
    wal:
      compression: gzip
    data:
      compression: gzip
  retentionPolicy: "7d"

7d는 이 실습에서 선택한 복구 보관 창이다. 단순히 생성 후 7일 지난 파일을 모두 지운다는 뜻은 아니다. 그 구간의 시작점을 복구하는 데 필요한 이전 백업도 남을 수 있다. 버킷의 별도 lifecycle 규칙이 필요한 WAL을 먼저 지우지 않도록 맞춘다. (보관 정책)

Cluster에 WAL archiver 연결

기존 cluster.yaml의 spec 아래에 다음을 병합한다. 다른 설정은 유지한다. 이 발췌만 별도 Cluster 파일처럼 apply하지 않는다.

plugins:
  - name: barman-cloud.cloudnative-pg.io
    isWALArchiver: true
    parameters:
      barmanObjectName: study-backups

ObjectStore는 위치, 플러그인 연결은 그 위치로 WAL과 백업을 보내는 실행 경로를 정한다. 이것만으로 원하는 주기의 베이스 백업이 자동 예약되는 것은 아니다. (플러그인 사용법)

kubectl apply --dry-run=server -f object-store.yaml
kubectl apply -f object-store.yaml
kubectl apply --dry-run=server -f cluster.yaml
kubectl apply -f cluster.yaml
kubectl cnpg status -n pg-study study-pg

베이스 백업 요청

backup.yaml로 저장한다.

apiVersion: postgresql.cnpg.io/v1
kind: Backup
metadata:
  name: study-pg-base
  namespace: pg-study
spec:
  cluster:
    name: study-pg
  method: plugin
  pluginConfiguration:
    name: barman-cloud.cloudnative-pg.io

kubectl apply -f backup.yaml
kubectl get backup -n pg-study study-pg-base -w

완료 상태는 completed다. 확인 후 Ctrl+C로 관찰을 끝낸다. 같은 Backup 객체를 다시 apply한다고 새 백업이 반복 실행되지는 않는다. 새 요청에는 새 이름을 쓴다.

정기 실행은 별도 scheduled-backup.yaml에 둔다.

apiVersion: postgresql.cnpg.io/v1
kind: ScheduledBackup
metadata:
  name: study-pg-daily
  namespace: pg-study
spec:
  schedule: "0 0 3 * * *"
  backupOwnerReference: self
  cluster:
    name: study-pg
  method: plugin
  pluginConfiguration:
    name: barman-cloud.cloudnative-pg.io

kubectl apply -f scheduled-backup.yaml로 등록한다. 스케줄은 초·분·시·일·월·요일의 여섯 칸이다. 실제 운영 시간대와 생성 시각을 확인해 예약 의도를 맞춘다. (ScheduledBackup)

세 종류의 증거 확인

증거	확인할 것
Backup 상태	completed, 시작·종료 시각, 실패 이유
연속 WAL 아카이브	`kubectl cnpg status`와 아카이브 성공·실패 추이
실제 복원	별도 Cluster에서 목표 데이터와 시점 확인

아카이브가 막히면 복구 가능 구간이 뒤처지고 로컬 WAL 공간도 위험해질 수 있다. 백업 파일 크기가 늘었다는 관찰만으로 성공 처리하지 않는다.

예약을 멈출 때는 kubectl delete -f scheduled-backup.yaml을 사용한다. Backup CR 삭제와 오브젝트 저장소의 백업 파일 삭제는 같은 일이 아니다. 저장된 백업은 보관 정책과 별도 정리 절차로 관리하고 복원 확인이 끝나기 전에 지우지 않는다.