3.1 Operator 설치와 업그레이드

CloudNativePG는 Kubernetes 클러스터에 Operator 하나를 배치하는 것으로 시작합니다. Operator는 기본적으로 cnpg-system namespace에 Deployment로 설치되며, 이후 모든 Cluster·백업·복제 리소스를 이 Operator가 감시하고 조정합니다. 설치 방식은 매니페스트 직접 적용, Helm, OLM 세 갈래이고, 어느 쪽을 골라도 결과물은 동일한 controller manager Pod입니다.

설치 전 확인

노트

Operator는 클러스터 전역 리소스(CRD, ClusterRole 등)를 생성하므로 cluster-admin 권한이 필요합니다. 하나의 Kubernetes 클러스터에는 CloudNativePG Operator를 하나만 둡니다 — namespace를 나눠도 여러 Operator를 동시에 돌리는 구성은 지원하지 않습니다.

매니페스트로 설치

가장 단순한 방식은 릴리스 매니페스트를 kubectl로 직접 적용하는 것입니다. server-side apply를 쓰는 이유는 CRD가 커서 client-side apply의 annotation 크기 제한에 걸릴 수 있기 때문입니다.

매니페스트 적용

kubectl apply --server-side -f \
  https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.30/releases/cnpg-1.30.0.yaml

배포 상태 확인

kubectl rollout status deployment \
  -n cnpg-system cnpg-controller-manager

deployment "cnpg-controller-manager" successfully rolled out이 나오면 준비 완료입니다.

감시 namespace 지정

기본값은 클러스터 전역 감시입니다. 특정 namespace만 감시하도록 좁히려면 cnpg 플러그인으로 매니페스트를 생성한 뒤 적용합니다.

kubectl cnpg install generate \
  --watch-namespace "specific-namespace" \
  > cnpg_for_specific_namespace.yaml

Helm으로 설치

Helm을 쓰면 values 파일로 설정을 관리하고 업그레이드도 helm upgrade로 통일할 수 있습니다. 공식 chart 저장소는 cloudnative-pg/charts입니다.

경고

Deployment 이름이 설치 방식에 따라 다릅니다. 매니페스트·플러그인 설치는 cnpg-controller-manager, Helm 설치는 cnpg-cloudnative-pg입니다. 이후 rollout restart·rollout status 명령에서 이름을 맞춰야 합니다.

OLM·OpenShift

Operator Lifecycle Manager 환경에서는 OperatorHub.io를 통해 설치합니다. Red Hat OpenShift에서는 인증(certified) 버전이 Red Hat 카탈로그로 제공됩니다.

배포 형태

기본 설치는 단일 replica Deployment입니다. 대부분의 환경에서 이 구성으로 충분합니다. Operator 자체의 고가용성이 필요하면 replica를 늘리고 leader election을 켜서, 한 Pod가 죽어도 다른 Pod가 리더를 이어받게 할 수 있습니다. Operator가 잠깐 내려가도 이미 떠 있는 PostgreSQL 인스턴스는 계속 서비스하므로, Operator 자체의 다중화는 조정(reconcile) 지연을 줄이는 목적입니다.

업그레이드

Operator 업그레이드는 두 단계로 진행됩니다.

1. controller 업그레이드 — 새 버전 매니페스트를 적용하거나 Helm으로 올립니다.
2. instance manager 업그레이드 — controller가 올라간 뒤 각 인스턴스의 instance manager가 자동으로 갱신됩니다.

rolling update와 in-place update

기본값은 rolling update입니다. PostgreSQL 인스턴스를 하나씩 순차 재시작하며, primary는 replica로 switchover한 뒤 교체합니다. 이 과정에서 짧은 순단이 발생합니다.

in-place update는 opt-in 기능으로, instance manager만 갱신하고 PostgreSQL은 재시작하지 않으며 switchover도 일으키지 않습니다. Operator 설정에서 환경변수 ENABLE_INSTANCE_MANAGER_INPLACE_UPDATES를 'true'로 설정해 켭니다.

경고

in-place update는 이미 떠 있는 Pod를 직접 수정하므로 Pod의 immutability(불변성) 보장을 깨뜨립니다. 순단을 피하는 이점과 맞바꾸는 트레이드오프이므로, 재시작 비용이 큰 환경에서 선택적으로 씁니다.

switchover 정책

primary 교체 시 동작은 Cluster의 primaryUpdateStrategy로 제어합니다.

값	동작
unsupervised (기본)	switchover를 자동 완료. 짧은 순단 가능
supervised	새 primary 승격을 DBA가 수동으로 진행

rollout 간격 조절

여러 Cluster나 인스턴스가 동시에 재기동되어 부하가 몰리는 것을 막으려면 Operator 설정에서 지연을 줍니다.

파라미터	의미	기본값
CLUSTERS_ROLLOUT_DELAY	서로 다른 Cluster 업그레이드 사이 대기(초)	0
INSTANCES_ROLLOUT_DELAY	같은 Cluster 내 인스턴스 사이 대기(초)	0

지원 버전과 릴리스 정책

CloudNativePG는 semantic versioning(<major>.<minor>.<patch>)을 따르며, 같은 API 버전(현재 v1) 안에서는 하위 호환을 유지합니다. minor 릴리스는 약 3개월마다 나오고, 각 minor는 다음 minor(N+1)가 나온 뒤 3개월까지 지원됩니다. 이 3개월이 업그레이드 계획을 세울 시간입니다. LTS 같은 장기 지원 버전은 따로 없습니다. 즉 어느 버전이든 6개월 남짓 안에 다음 minor로 올라가야 보안 패치를 계속 받습니다.

버전	릴리스	지원 종료	Kubernetes	PostgreSQL
1.30.x	2026-06-29	2026-12 (예정)	1.34, 1.35, 1.36	14 ~ 18
1.29.x	2026-03-31	2026-09-29	1.33, 1.34, 1.35	14 ~ 18

다음 minor인 1.31.0은 공식 일정표에 2026년 9월경으로 예고되어 있으나, 2026-09-28 기준으로는 아직 출시되지 않았습니다(최신은 1.30.1, 1.29.3). 지원하는 Kubernetes는 minor마다 세 버전씩 앞으로 밀리므로, Kubernetes 업그레이드와 Operator 업그레이드는 짝지어 계획하는 편이 안전합니다. PostgreSQL은 커뮤니티가 지원하는 major를 따라가며, 14는 2026-11-12에 지원이 끝납니다.

Operator를 올릴 때는 버전을 건너뛰지 말고 minor 순서대로 올리는 것을 권합니다. 최신 일정은 공식 Supported releases 페이지에 있습니다.

노트

1.30.0(및 1.29.2, 1.28.4)에는 보안 관련 동작 변경이 포함됩니다. 특히 Operator가 접속 시 search_path를 pg_catalog, public, pg_temp로 고정하므로, 사용자 스키마를 참조하는 커스텀 모니터링 쿼리는 myschema.mytable처럼 스키마를 명시해야 합니다. 또한 password가 Operator 측에서 SCRAM-SHA-256으로 인코딩됩니다. 업그레이드 전 릴리스 노트를 반드시 확인합니다.

정리

• 설치는 매니페스트·Helm·OLM 세 갈래이고, 어느 쪽이든 결과물은 cnpg-system의 controller manager Deployment 하나입니다. 클러스터당 Operator는 하나로 유지합니다.
• 업그레이드는 controller를 먼저 올리면 instance manager가 자동으로 뒤따릅니다. 기본은 rolling update, in-place는 opt-in입니다.
• 1.30으로 올릴 때는 search_path 고정과 password 인코딩 같은 동작 변경이 있으니 릴리스 노트를 먼저 확인합니다.