3.1 Operator 설치와 업그레이드

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

    flowchart TD
  M["설치 방식 선택"]
  Y["kubectl apply<br/>매니페스트"]
  H["Helm chart"]
  O["OLM / OperatorHub"]
  D["cnpg-system<br/>Deployment"]
  R["controller-manager<br/>Pod 기동"]
  W["Cluster 리소스 감시"]

  M --> Y
  M --> H
  M --> O
  Y --> D
  H --> D
  O --> D
  D --> R --> W

  classDef step fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
  class M,Y,H,O,D,R,W step
  

설치 전 확인

매니페스트로 설치

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

감시 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다.

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가 자동으로 갱신된다.

    flowchart TD
  A["새 매니페스트 적용"]
  B["controller 교체"]
  C["instance manager<br/>갱신 시작"]
  D{"업데이트 방식"}
  E["rolling update<br/>replica부터 순차"]
  F["in-place<br/>재시작 없음"]
  G["switchover<br/>후 primary 교체"]

  A --> B --> C --> D
  D -- "기본" --> E --> G
  D -- "opt-in" --> F

  classDef step fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
  class A,B,C,E,F,G step
  

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' 로 설정해 켠다.

switchover 정책

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

rollout 간격 조절

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

버전 호환성

CloudNativePG는 semantic versioning을 따르며, 같은 API 버전(현재 v1) 안에서는 하위 호환을 유지한다. 릴리스는 대체로 월 단위로 나오므로, 자주 올리기 어렵다면 버전을 건너뛰지 말고 순차적으로 업그레이드하기를 권한다.

정리

• 설치는 매니페스트·Helm·OLM 세 갈래, 결과물은 cnpg-system의 controller manager Deployment
• 하나의 Kubernetes 클러스터에는 Operator 하나만
• 업그레이드는 controller 먼저, instance manager 자동 후속 — 기본은 rolling, in-place는 opt-in
• 1.30 업그레이드 전 search_path·password 인코딩 등 동작 변경을 릴리스 노트로 확인

다음 절(3.2)에서는 PostgreSQL 이미지를 Cluster 정의에서 떼어 내 선언적으로 관리하는 Image Catalog를 본다.