1.1 CloudNativePG란 무엇인가

CloudNativePG는 Kubernetes 클러스터 위에서 PostgreSQL 워크로드를 운영하도록 설계된 오픈소스 Operator다. 원래 EDB가 개발했고 Apache License 2.0으로 공개되어 있으며, Cloud Native Computing Foundation(CNCF)의 Sandbox 프로젝트다. 이 책에서는 짧게 CNPG로도 부른다.

한 문장으로 줄이면, PostgreSQL 클러스터를 하나의 Kubernetes 리소스로 선언하면 나머지 운영을 Operator가 대신 처리한다는 것이다. 이 절에서는 그 전제인 Operator 개념부터, 왜 데이터베이스를 컨테이너와 Kubernetes 위에서 돌리는지, 전통적인 방식과 무엇이 다른지를 정리한다.

Kubernetes Operator란

Kubernetes는 컨테이너를 배포하고 스케일링하는 데는 뛰어나지만, 그 자체로는 “PostgreSQL의 primary가 죽으면 replica를 승격하라” 같은 애플리케이션 고유의 운영 지식을 알지 못한다. 이런 지식은 원래 사람 운영자(operator)의 머릿속과 절차서에 있었다.

Operator는 그 사람 운영자가 하던 절차를 코드로 옮겨 Kubernetes 안에 심은 것이다. 공식 정의로는 “사람 운영자가 통상 수행하던 단계를 자동화하는 custom resource"다. 두 가지 조각으로 이뤄진다.

CRD(Custom Resource Definition): Kubernetes API를 확장해 새로운 리소스 타입을 정의한다. CNPG는 Cluster라는 리소스 타입을 추가한다. 덕분에 kubectl로 Pod나 Service를 다루듯 PostgreSQL 클러스터를 다룰 수 있다.
Controller: 그 리소스를 계속 지켜보며 “선언된 상태(desired state)“와 “실제 상태(actual state)“의 차이를 줄이는 제어 루프. primary가 사라지면 replica를 승격하고, 인스턴스 수가 모자라면 새 Pod를 만든다.

    flowchart TD
    DBA[DBA] -->|Cluster 매니페스트 적용| API[Kubernetes API]
    API --> OP[CNPG Operator]
    OP -->|상태 비교·조정| API
    OP -.감시.-> PODS[PostgreSQL Pod들]
    OP -.감시.-> API

핵심은 선언형(declarative) 이라는 점이다. “이렇게 만들어라"라는 절차를 하나씩 지시하는 대신, “primary 1개와 replica 2개로 구성된 클러스터가 있어야 한다"는 원하는 결과만 선언한다. 어떻게 거기에 도달하고 어떻게 그 상태를 유지할지는 Operator의 몫이다.

왜 PostgreSQL을 Kubernetes 위에서 돌리는가

전통적으로 데이터베이스는 “특별한 존재"로 취급됐다. 물리 서버나 VM에 사람이 직접 설치하고, high availability를 위해 Patroni·repmgr·Pacemaker 같은 도구와 스크립트를 조합하고, 장애가 나면 절차서를 보며 수동으로 failover했다. 애플리케이션은 컨테이너로 빠르게 배포되는 반면, 데이터베이스만 손으로 관리되는 섬처럼 남는 경우가 많았다.

CNPG는 그 격차를 메운다. PostgreSQL을 Kubernetes의 다른 워크로드와 동일한 방식으로 다루면 다음을 얻는다.

선언형 운영: 클러스터 구성·리소스·백업 정책을 YAML로 선언하고 Git으로 버전 관리한다(GitOps).
자동 복구: primary 장애 시 Operator가 자동으로 failover하고 새 standby를 다시 만든다. 사람의 개입 없이 self-healing이 동작한다.
애플리케이션과의 동거: 애플리케이션과 데이터베이스를 같은 namespace에 두는 microservice database 방식이 가능하다. 배포·네트워크·보안을 하나의 플랫폼에서 일관되게 다룬다.
이식성: 특정 클라우드 벤더의 관리형 DB에 종속되지 않고, 지원되는 어떤 Kubernetes 클러스터에서도 같은 매니페스트로 동작한다.

CNPG의 자동 failover는 사람이 절차서를 보고 하던 대응을 자동화한 것이지, 데이터 손실이 없다는 보장은 아니다. Zero-Data-Loss가 필요하면 synchronous replication을 별도로 구성해야 한다. 자세한 내용은 뒤의 high availability 파트에서 다룬다.

전통적 방식과의 차이

항목	전통적 방식 (VM·베어메탈)	CloudNativePG
설치	수동 설치·설정	Cluster 매니페스트 선언
High Availability	Patroni/repmgr + 스크립트 조합	Operator 내장
Failover	수동 또는 외부 도구	자동 (self-healing)
구성 관리	절차서·Ansible	선언형 YAML + GitOps
스토리지	직접 마운트	PVC로 동적 프로비저닝
접속 지점	고정 IP·VIP	Kubernetes Service

CNPG의 아키텍처와 위치

CNPG는 몇 가지 리소스를 층으로 쌓아 PostgreSQL 클러스터를 표현한다.

Operator: 전체를 관리하는 control plane. cnpg-system namespace의 controller Pod로 동작한다.
Cluster (CRD): 하나의 PostgreSQL 클러스터를 나타내는 custom resource. primary 1개와 선택적 replica들로 구성된다.
Pod: 각 PostgreSQL 인스턴스가 개별 Pod로 뜬다. 각 Pod 안에는 인스턴스를 관리하는 자체 instance manager가 함께 들어 있다.
PVC(Persistent Volume Claim): 데이터(PGDATA), WAL, tablespace용 영속 스토리지. 하나의 인스턴스가 쓰는 관련 PVC들을 PVC Group이라 부른다.

    flowchart TD
    C[Cluster 리소스] --> OP[CNPG Operator]
    OP --> P1[Primary Pod]
    OP --> P2[Replica Pod]
    OP --> P3[Replica Pod]
    P1 --- V1[(PVC PGDATA/WAL)]
    P2 --- V2[(PVC PGDATA/WAL)]
    P3 --- V3[(PVC PGDATA/WAL)]
    P1 -.streaming replication.-> P2
    P1 -.streaming replication.-> P3

CNPG는 stateful 워크로드에 흔히 쓰이는 StatefulSet을 사용하지 않는다. 대신 각 인스턴스를 Operator가 직접 관리하는 개별 Pod와 PVC로 다룬다. 그래야 failover·재구성 같은 PostgreSQL 고유 동작을 세밀하게 제어할 수 있기 때문이다.

버전과 이미지 기본값

CNPG 1.30은 별도 지정이 없으면 operand 이미지로 ghcr.io/cloudnative-pg/postgresql:18.4-system-trixie를 배포한다. 즉 기본 PostgreSQL은 18 계열이다. 특정 버전이 필요하면 Cluster의 imageName으로 오버라이드한다.

Kubernetes 버전은 커뮤니티가 지원하는 릴리스를 따른다. 구체적인 지원 범위는 공식 Supported releases 문서를 참고한다.

다음 절에서는 애플리케이션이 Kubernetes 안에 있을 때와 밖에 있을 때 CNPG를 어떻게 연결하는지, 대표적인 사용 사례를 살펴본다.

1.2 사용 사례