본문으로 건너뛰기

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

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

CloudNativePG Quickstart 실행 순서

준비물​

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

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

절차​

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

kind​

kind create cluster --name pg

minikube​

minikube start
kubectl get nodes   # node가 Ready인지 확인

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:17.6-minimal-trixie
  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

배포 결과 한눈에 보기​

경고

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

정리​

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