본문으로 건너뛰기
Docs
Part XI. 운영 도구와 트러블슈팅
11.1 cnpg kubectl 플러그인

11.1 cnpg kubectl 플러그인

cnpg는 kubectl의 플러그인이다. kubectl 뒤에 cnpg를 붙여 kubectl cnpg status처럼 실행하면, CloudNativePG 클러스터를 다루는 데 필요한 여러 동작을 하나의 명령으로 처리해 준다. 순수 kubectl로도 같은 일을 할 수 있지만, 클러스터 상태를 보려면 여러 리소스를 조합해 조회해야 하고 백업을 걸려면 Backup 리소스를 직접 작성해야 한다. 플러그인은 이 과정을 짧은 서브커맨드로 감싼 것이다.

    flowchart TD
  DBA["DBA"] -->|kubectl cnpg ...| PLUG["cnpg 플러그인"]
  PLUG -->|조회·패치| API["Kubernetes API"]
  API --> CR["Cluster / Backup"]
  API --> POD["Pod (postgres)"]
  PLUG -.->|exec| POD

  classDef node fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
  class DBA,PLUG,API,CR,POD node

플러그인은 API를 거쳐 리소스를 읽고 패치하며, 필요할 때는 Pod 안에서 직접 명령을 실행(exec)한다. 그래서 플러그인의 각 명령이 실제로 어떤 Kubernetes 권한을 요구하는지 알아 두면 RBAC를 좁게 잡을 때 도움이 된다.

설치

플러그인은 별도의 바이너리이며 여러 방식으로 설치한다. 가장 간단한 것은 설치 스크립트다.

curl -sSfL \
  https://github.com/cloudnative-pg/cloudnative-pg/raw/main/hack/install-cnpg-plugin.sh | \
  sudo sh -s -- -b /usr/local/bin

설치가 끝나면 버전으로 확인한다.

kubectl cnpg version
플러그인 이름은 kubectl-cnpg이지만 실행할 때는 kubectl cnpg로 띄어 쓴다. kubectl이 kubectl- 로 시작하는 실행 파일을 자동으로 서브커맨드로 인식하는 규칙 덕분이다. Debian·RPM 패키지, Arch AUR도 제공되며 Linux·macOS·Windows를 모두 지원한다.

status: 클러스터 상태 한눈에

가장 자주 쓰는 명령이다. 클러스터 이름을 넘기면 PostgreSQL system ID, 현재 timeline, WAL 위치, 각 인스턴스의 역할과 복제 지연을 한 화면에 모아 보여 준다.

kubectl cnpg status sandbox
kubectl cnpg status sandbox -n my-namespace   # 네임스페이스 지정
kubectl cnpg status sandbox --verbose         # 더 자세히 (-v 반복 가능)

출력에는 primary가 어느 Pod인지, replica들이 얼마나 따라왔는지, 마지막으로 복구 가능한 백업 지점이 언제인지가 포함된다. 장애를 의심할 때 가장 먼저 실행하는 명령이다.

promote: primary 승격

특정 인스턴스를 primary로 올린다. 계획된 switchover를 테스트하거나, 유지보수를 위해 primary를 다른 Pod로 옮길 때 쓴다.

kubectl cnpg promote sandbox sandbox-2   # Pod 이름으로
kubectl cnpg promote sandbox 2           # 인스턴스 번호로

backup: 온디맨드 백업

설정된 백업 정책에 따라 즉시 물리 백업을 만든다. 백업 이름은 요청 시각에서 자동 생성된다.

kubectl cnpg backup sandbox
kubectl cnpg backup sandbox -m volumeSnapshot   # volume snapshot 방식

주요 플래그로는 대상 인스턴스를 고르는 --backup-target, volume snapshot의 hot backup을 위한 --online, checkpoint 동작을 조절하는 --immediate-checkpoint, archive 동기화를 기다리는 --wait-for-archive가 있다.

psql: 클러스터에 바로 접속

primary Pod 안에서 psql을 띄워 대화형 세션을 연다. 접속 문자열이나 비밀번호를 따로 다룰 필요 없이 클러스터 이름만 넘기면 된다.

kubectl cnpg psql cluster-example                    # primary, postgres 사용자
kubectl cnpg psql --replica cluster-example          # replica(standby)에 접속
kubectl cnpg psql cluster-example -- appdb           # 특정 데이터베이스
kubectl cnpg psql cluster-example -- -c "SELECT 1"   # 쿼리 한 줄 실행

-- 뒤에 오는 인자는 그대로 psql에 전달된다.

psql 명령은 Pod 안에서 실행되므로, 로컬에 psql 클라이언트가 없어도 동작한다. 다만 운영 트래픽이 몰리는 primary에 직접 붙는 것이므로, 무거운 조회는 --replica로 standby에 붙여 primary 부하를 피한다.

report: 진단 자료 묶기

문제를 보고하거나 지원을 요청할 때 필요한 정보를 ZIP으로 모은다. Operator 대상과 클러스터 대상이 나뉜다.

# Operator 배포·설정·이벤트·로그 수집
kubectl cnpg report operator -n cnpg-system -f operator-report.zip
kubectl cnpg report operator -n cnpg-system --logs   # 로그 포함

# 특정 클러스터의 리소스·Pod·Job·이벤트 수집
kubectl cnpg report cluster sandbox -n my-namespace --logs

기본적으로 Secret 값은 가려진(redacted) 채로 담긴다. -S 플래그로 이 가림을 끌 수 있지만, 자격 증명이 그대로 노출되므로 권장하지 않는다.

restart와 reload

restart는 클러스터 전체를 순차 재시작하거나 특정 인스턴스만 재시작한다. primary는 가능하면 제자리에서 재시작하고, 변경이 switchover를 요구하면 역할을 넘긴 뒤 재시작한다. replica는 삭제 후 재생성된다.

kubectl cnpg restart sandbox            # 전체 rolling restart
kubectl cnpg restart sandbox sandbox-2  # 한 인스턴스만

reload는 재시작 없이 Operator의 조정 루프를 다시 돌려, 변경된 ConfigMap 같은 종속 오브젝트를 반영한다.

kubectl cnpg reload sandbox

logs: 로그 모아 보기

클러스터 모든 인스턴스의 로그를 하나의 스트림으로 합쳐 준다. 기본 출력은 JSON lines 형식이다.

kubectl cnpg logs cluster sandbox -f              # 실시간 추적
kubectl cnpg logs cluster sandbox -f --tail 3     # 각 Pod 마지막 3줄부터
kubectl cnpg logs cluster sandbox --output out.log

JSON 로그는 사람이 읽기 불편하므로 logs pretty로 넘겨 정렬·정형화한다.

kubectl cnpg logs cluster sandbox | kubectl cnpg logs pretty
kubectl cnpg logs cluster sandbox | \
  kubectl cnpg logs pretty --loggers postgres --log-level info

그 밖의 명령

명령하는 일
install generateOperator 배포용 YAML 매니페스트 생성
certificate클러스터 CA가 서명한 TLS 클라이언트 인증서 발급
destroy CLUSTER INSTANCE인스턴스 Pod와 PVC 제거 (--keep-pvc로 PVC 보존)
maintenance set/unset노드 유지보수 창(nodeMaintenanceWindow) 설정
hibernate on/off클러스터 일시정지 (11.4)
fencing on/off인스턴스 격리 (11.3)
pgbench클러스터 대상 pgbench 벤치마크 실행
fiostorage class 대상 I/O 벤치마크 실행

install generate는 설치 매니페스트를 파일로 뽑아 GitOps로 관리할 때 유용하다.

kubectl cnpg install generate -n cnpg-system --version 1.30 \
  --replicas 3 --watch-namespace "app-a,app-b" > operator.yaml

권한 관점에서 보기

플러그인 명령마다 필요한 Kubernetes 권한이 다르다. 예를 들어 status는 clusters를 읽고 pods에 exec·proxy할 수 있으면 되지만, destroy는 pods·PVC를 삭제할 권한까지 요구한다. 최소 권한 원칙으로 RBAC를 설계할 때, 담당자가 실제로 쓰는 명령만 골라 권한을 부여하면 된다.

명령요구 권한(요약)
statusclusters get / pods list·exec·proxy
backupclusters get / backups create
promoteclusters get·status patch / pods get
destroypods·PVC·jobs delete
report operatordeployments get (로그·Secret은 선택)

정리

  • cnpg는 kubectl 플러그인. 상태 조회·백업·진단을 짧은 명령으로 묶는다
  • status가 진단의 출발점 — 역할·복제 지연·백업 지점을 한눈에
  • psql·logs로 접속과 로그 확인, report로 지원용 자료 수집
  • restart·reload·promote로 운영 동작을 안전하게 트리거
  • 명령별 요구 권한이 다르므로 최소 권한 RBAC 설계에 참고

다음 절(11.2)에서는 이 도구들을 실제 문제 진단에 어떻게 엮는지, 트러블슈팅 절차를 본다.

11.2 트러블슈팅