← 아티클 목록

쿠버네티스 StatefulSet — 안정적 스토리지·순서 보장 정리

2027-07-05#kubernetes#statefulset#스토리지

PostgreSQL이나 Kafka를 Deployment로 띄웠다가 Pod가 재시작될 때마다 데이터가 사라지거나 이름이 바뀌어서 클러스터 멤버십이 깨진 경험이 있다면, 그건 워크로드 종류를 잘못 고른 것입니다. Deployment는 모든 Pod를 "교체 가능한 똑같은 일꾼"으로 취급합니다. 하지만 DB의 0번 노드와 1번 노드는 같지 않습니다. 각자 고유한 데이터와 정체성을 가져야 하죠. 이때 쓰는 것이 StatefulSet입니다.

Deployment와 무엇이 다른가

항목DeploymentStatefulSet
Pod 이름랜덤 해시 (web-7d9f-x2k)고정 인덱스 (db-0, db-1)
스토리지공유 또는 임시Pod마다 전용 PVC
기동 순서동시·무작위0 → 1 → 2 순차
종료 순서무작위역순 (2 → 1 → 0)
네트워크 IDService로 부하분산Pod별 고정 DNS

핵심은 각 Pod가 고유하고 안정적인 정체성을 가진다는 점입니다. db-0은 재시작해도 계속 db-0이고, 자기 PVC에 다시 붙습니다.

최소 예제

StatefulSet은 반드시 Headless Service(clusterIP: None)와 짝을 이룹니다. 이 Service가 db-0.db 같은 Pod별 DNS를 만들어 줍니다.

YAML
apiVersion: v1
kind: Service
metadata:
  name: db
spec:
  clusterIP: None      # Headless — Pod별 DNS 발급
  selector:
    app: db
  ports:
    - port: 5432
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: db
spec:
  serviceName: db      # 위 Headless Service 이름과 일치해야 함
  replicas: 3
  selector:
    matchLabels:
      app: db
  template:
    metadata:
      labels:
        app: db
    spec:
      containers:
        - name: postgres
          image: postgres:16
          ports:
            - containerPort: 5432
          volumeMounts:
            - name: data
              mountPath: /var/lib/postgresql/data
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi

volumeClaimTemplates가 핵심입니다. 이게 있으면 쿠버네티스가 Pod마다 data-db-0, data-db-1 PVC를 자동 생성합니다. Pod가 죽었다 살아나도 같은 PVC에 다시 마운트되므로 데이터가 유지됩니다.

동작 확인

Kubernetes
kubectl get pods -l app=db          # db-0, db-1, db-2 순서대로
kubectl get pvc                     # data-db-0 ~ data-db-2
kubectl exec db-0 -- nslookup db-1.db   # Pod별 DNS 해석 확인

기동을 지켜보면 db-0이 Running이 된 다음에야 db-1이 생성됩니다. 이 순차성 덕분에 "0번을 프라이머리로, 나머지를 레플리카로" 같은 초기화 로직을 안전하게 짤 수 있습니다.

흔한 함정 체크리스트

Kubernetes
# serviceName이 실제 Headless Service와 일치하는가
kubectl get svc db -o jsonpath='{.spec.clusterIP}'   # None 이어야 함

# PVC가 Pending이면 StorageClass·프로비저너 확인
kubectl get pvc
kubectl describe pvc data-db-0

# StatefulSet 삭제 시 PVC는 자동 삭제 안 됨 — 수동 정리 필요
kubectl delete pvc -l app=db

특히 마지막 항목이 중요합니다. StatefulSet을 지워도 PVC는 데이터 보호를 위해 남습니다. 의도적으로 비우려면 직접 지워야 합니다.

StatefulSet의 순차 기동과 PVC 동작을 실제 클러스터에서 띄워 보며 확인하는 실습은 쿠버네티스 트랙에서 회원가입 없이 무료로 해볼 수 있습니다.