1.3 Quickstart: 5분 만에 첫 클러스터

로컬 Kubernetes에 CloudNativePG Operator를 설치하고, PostgreSQL Cluster를 하나 띄워 접속까지 해 본다. 여기서는 가벼운 로컬 클러스터인 kind를 기준으로 설명한다. minikube도 동일하게 쓸 수 있다.

준비물

kubectl (Kubernetes 공식 문서의 설치 안내를 따른다)
kind 또는 minikube 중 하나
Docker 등 컨테이너 런타임 (kind가 내부적으로 사용)

kind(Kubernetes IN Docker)는 Docker 컨테이너를 node로 삼아 로컬에 Kubernetes 클러스터를 띄우는 도구다. 실제 서버 없이 노트북에서 CNPG를 실습하기에 적합하다. 프로덕션 용도는 아니다.

절차

Step 1. 로컬 Kubernetes 클러스터 생성

kind create cluster --name pg

Step 2. CloudNativePG Operator 설치

1.30 릴리스의 매니페스트를 --server-side 모드로 적용한다.

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

Operator가 정상적으로 떴는지는 rollout 상태로 확인한다.

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

successfully rolled out 메시지가 나오면 Operator가 cnpg-system namespace에서 동작 중이다.

Step 3. Cluster 매니페스트 작성

cluster-example.yaml 파일을 만든다. primary 1개 + replica 2개, 총 3개 인스턴스 구성이다.

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example
spec:
  instances: 3
  storage:
    size: 1Gi

instances: 3은 primary 1개와 replica 2개를 뜻한다. Operator가 그중 하나를 primary로 선출하고 나머지를 streaming replication으로 붙인다. storage.size는 각 인스턴스의 PVC 크기다. 이미지를 지정하지 않았으므로 1.30 기본값인 PostgreSQL 18 계열 이미지가 쓰인다.

특정 PostgreSQL 버전이 필요하면 spec에 imageName을 추가한다.

spec:
  instances: 3
  imageName: ghcr.io/cloudnative-pg/postgresql:13.6
  storage:
    size: 1Gi

Step 4. Cluster 배포

kubectl apply -f cluster-example.yaml

Step 5. 상태 확인

Pod가 뜨는 과정을 지켜본다.

kubectl get pods -l cnpg.io/cluster=cluster-example

인스턴스가 모두 준비되면 3개의 Pod가 Running 상태로 보인다. cnpg kubectl 플러그인을 설치했다면 사람이 읽기 좋은 요약도 볼 수 있다.

kubectl cnpg status cluster-example

여기에는 어느 Pod가 primary이고 어느 것이 replica인지, replication 지연은 얼마인지 등이 표시된다.

Step 6. 접속

cnpg 플러그인으로 primary에 곧장 psql 세션을 연다.

kubectl cnpg psql cluster-example

애플리케이션 관점에서는 개별 Pod가 아니라 Operator가 만들어 준 service를 통해 접속한다. read-write 트래픽은 cluster-example-rw service가 항상 현재 primary를 가리킨다.

kubectl get svc -l cnpg.io/cluster=cluster-example

배포 결과 한눈에 보기

    flowchart TD
    M[cluster-example.yaml] -->|kubectl apply| OP[CNPG Operator]
    OP --> RW[cluster-example-rw Service]
    OP --> PRI[Primary Pod]
    OP --> R1[Replica Pod]
    OP --> R2[Replica Pod]
    RW --> PRI
    PRI -.replication.-> R1
    PRI -.replication.-> R2

이 구성은 실습용이다. storage.size: 1Gi와 단일 node kind 클러스터는 프로덕션 기준을 충족하지 못한다. 실제 운영에서는 스토리지 용량·backup·리소스 요청/제한·node 분산(affinity)을 반드시 함께 설계한다. 이후 파트에서 다룬다.

정리

Operator 매니페스트 하나를 적용하고, 인스턴스 수와 스토리지 크기만 담은 짧은 Cluster 매니페스트를 선언하면 high availability PostgreSQL 클러스터가 뜬다. failover·service 배선·replication 구성은 Operator가 알아서 처리한다.

1.2 사용 사례 1.4 Operator 성숙도 단계