Deployment로 만든 파드는 언제든 지워지고 다시 만들어져도 괜찮은, 서로 구분할 필요 없는 복제본입니다. 그래서 이름도 web-7d9c5b6f4-x2k8p처럼 무작위로 붙고, 어느 파드가 요청을 받아도 결과가 같아야 합니다. 이 방식은 웹 서버처럼 상태가 없는(stateless) 애플리케이션에는 잘 맞습니다.
하지만 데이터베이스, 메시지 브로커, 분산 저장소처럼 상태를 가진(stateful) 애플리케이션은 사정이 다릅니다. "이 파드가 1번 노드(primary)이고 저 파드가 복제본(replica)이다"라는 구분이 필요하고, 파드가 재시작되어도 자기 데이터를 그대로 다시 붙잡아야 합니다. StatefulSet은 이런 요구를 위해 만들어진 워크로드입니다.
Deployment와 무엇이 다른가요?
| 구분 | Deployment | StatefulSet |
|---|---|---|
| 파드 이름 | 무작위 (web-7d9c5b6f4-x2k8p) | 순번이 붙은 고정 이름 (web-0, web-1) |
| 재시작 후 | 새 이름, 새 IP | 같은 이름으로 다시 만들어짐 (IP는 바뀔 수 있음) |
| 생성·삭제 순서 | 한꺼번에 | 순서대로 (0번부터 생성, 큰 번호부터 삭제) |
| 스토리지 | 보통 하나를 같이 쓰거나 임시 저장소 | 파드마다 전용 PersistentVolumeClaim |
| 네트워크 | Service 하나로 묶어서 접근 | 파드마다 고유한 DNS 이름 |
| 적합한 앱 | 웹 서버, API 서버 | DB, Kafka, ZooKeeper, Elasticsearch 등 |
쿠버네티스 공식 문서는 StatefulSet이 필요한 경우를 아래 네 가지로 정리합니다. 이 중 하나도 필요하지 않다면 Deployment를 쓰는 편이 더 단순합니다.
- 안정적이고 고유한 네트워크 식별자
- 안정적이고 영속적인 스토리지
- 순서가 있는 안전한 배포와 스케일링
- 순서가 있는 자동 롤링 업데이트
여기서 "안정적"이라는 말은 파드가 다시 스케줄링되어도 유지된다는 뜻입니다.
StatefulSet이 보장하는 세 가지
StatefulSet의 파드는 순번(ordinal), 안정적인 네트워크 ID, 안정적인 스토리지로 이루어진 정체성을 가집니다. 이 정체성은 파드가 어느 노드로 옮겨 가도 그대로 따라다닙니다.
1. 이름과 순번
레플리카가 N개이면 파드에는 기본적으로 0부터 N-1까지 순번이 붙고, 이름은 <StatefulSet 이름>-<순번>이 됩니다. 이름이 web이고 replicas: 3이면 web-0, web-1, web-2가 만들어집니다. web-1 파드가 지워지면 새로 만들어지는 파드도 반드시 web-1입니다.
2. 안정적인 네트워크 ID와 Headless Service
각 파드의 호스트 이름은 파드 이름과 같고, 파드마다 고유한 DNS 이름이 생깁니다.
<파드이름>.<서비스이름>.<네임스페이스>.svc.cluster.local
예) web-0.nginx.default.svc.cluster.local이 DNS 이름을 만들어 주는 것이 Headless Service입니다. 일반 Service는 clusterIP를 하나 받아 여러 파드로 부하를 나누지만, clusterIP: None으로 만든 Headless Service는 가상 IP 없이 파드 하나하나의 주소를 DNS로 알려 줍니다. StatefulSet은 spec.serviceName에 이 서비스의 이름을 적어 연결하며, 이 Service는 직접 만들어야 합니다. StatefulSet이 대신 만들어 주지 않습니다.
클러스터 안에서 이름을 IP로 바꿔 주는 부분은 CoreDNS가 담당합니다.
3. 파드마다 전용 스토리지 (volumeClaimTemplates)
Deployment에서 PVC 하나를 여러 파드가 같이 쓰는 것과 달리, StatefulSet은 volumeClaimTemplates에 적은 틀로 파드마다 PersistentVolumeClaim을 하나씩 만들어 줍니다. PVC 이름은 <템플릿 이름>-<파드 이름> 형식이고, 템플릿 이름이 www, 파드가 web-0이면 www-web-0이 됩니다.
파드가 재시작하거나 다른 노드로 옮겨 가도 같은 이름의 파드는 같은 PVC를 다시 마운트합니다. 그래서 web-0은 언제나 web-0의 데이터를 가집니다.
PVC가 자동으로 만들어지려면 클러스터에 동적 프로비저닝이 되는 StorageClass가 있거나, 조건에 맞는 PersistentVolume이 미리 있어야 합니다. StorageClass를 따로 적지 않으면 기본(default) StorageClass가 사용됩니다.
실습: nginx 두 개 띄우기
공식 튜토리얼의 예제를 그대로 따라가 봅니다. Headless Service와 StatefulSet을 한 파일에 담았습니다.
apiVersion: v1
kind: Service
metadata:
name: nginx
labels:
app: nginx
spec:
ports:
- port: 80
name: web
clusterIP: None
selector:
app: nginx
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: web
spec:
serviceName: 'nginx'
replicas: 2
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: registry.k8s.io/nginx-slim:0.21
ports:
- containerPort: 80
name: web
volumeMounts:
- name: www
mountPath: /usr/share/nginx/html
volumeClaimTemplates:
- metadata:
name: www
spec:
accessModes: ['ReadWriteOnce']
resources:
requests:
storage: 1Gi몇 가지 짚고 갑니다.
clusterIP: None이 Headless Service를 만드는 설정입니다.- StatefulSet의
serviceName은 위 Service의 이름(nginx)과 같아야 합니다. selector.matchLabels는template.metadata.labels와 일치해야 합니다. 맞지 않으면 생성할 때 검증 오류가 납니다.- 예제는 단순하게 하려고
ReadWriteOnce를 썼습니다. 공식 문서는 운영 환경에서는ReadWriteOncePod접근 모드를 권장합니다.
이 실습은 동적 프로비저닝이 되는 기본 StorageClass가 있는 클러스터를 전제로 합니다. 연습은 실제 서비스가 돌지 않는 클러스터의 default 네임스페이스에서 하는 것이 안전합니다.
1) 순서대로 만들어지는지 확인
터미널을 두 개 엽니다. 첫 번째에서 파드가 만들어지는 과정을 지켜봅니다.
$ kubectl get pods --watch -l app=nginx두 번째 터미널에서 적용합니다.
$ kubectl apply -f web.yaml
service/nginx created
statefulset.apps/web created첫 번째 터미널에는 아래와 비슷하게 나옵니다. 정확한 시간과 출력은 환경에 따라 다릅니다.
NAME READY STATUS RESTARTS AGE
web-0 0/1 Pending 0 0s
web-0 0/1 ContainerCreating 0 0s
web-0 1/1 Running 0 19s
web-1 0/1 Pending 0 0s
web-1 0/1 ContainerCreating 0 0s
web-1 1/1 Running 0 18sweb-1은 web-0이 Running이면서 Ready가 된 뒤에야 만들어집니다. 앞 번호가 준비되지 않으면 뒤 번호는 시작하지 않는다는 뜻입니다.
2) 이름과 DNS 확인
$ for i in 0 1; do kubectl exec "web-$i" -- sh -c 'hostname'; done
web-0
web-1DNS는 임시 파드에서 nslookup으로 확인합니다.
$ kubectl run -i --tty --image busybox:1.28 dns-test --restart=Never --rm
# 파드 안의 셸에서
$ nslookup web-0.nginxweb-0.nginx가 파드의 IP로 풀리면 성공입니다. 같은 네임스페이스 안에서는 web-0.nginx처럼 짧게 써도 되고, 다른 네임스페이스에서는 web-0.nginx.default.svc.cluster.local처럼 전체 이름을 씁니다.
여기서 한 가지 중요한 점이 있습니다. 파드를 지워서 다시 만들면 이름과 DNS 이름은 그대로이지만 IP는 바뀔 수 있습니다. 그래서 StatefulSet의 파드에 접속할 때는 IP를 설정에 박아 두지 말고 반드시 DNS 이름으로 연결해야 합니다.
3) 데이터가 남는지 확인
PVC를 먼저 봅니다.
$ kubectl get pvc -l app=nginx
NAME STATUS VOLUME CAPACITY ACCESS MODES AGE
www-web-0 Bound pvc-15c268c7-b507-11e6-932f-42010a800002 1Gi RWO 48s
www-web-1 Bound pvc-15c79307-b507-11e6-932f-42010a800002 1Gi RWO 48s파드마다 www-web-0, www-web-1이 하나씩 만들어졌습니다. 각 파드의 index.html에 자기 호스트 이름을 써 두고, 파드를 전부 지워 봅니다.
$ for i in 0 1; do kubectl exec "web-$i" -- sh -c 'echo "$(hostname)" > /usr/share/nginx/html/index.html'; done
$ kubectl delete pod -l app=nginx
pod "web-0" deleted
pod "web-1" deleted
# 파드가 다시 Running/Ready가 되면
$ for i in 0 1; do kubectl exec -i -t "web-$i" -- curl http://localhost/; done
web-0
web-1새로 만들어진 파드도 같은 PVC를 다시 마운트했기 때문에 쓴 내용이 그대로 남아 있습니다. 만약 403 Forbidden이 나오면 마운트된 디렉터리의 권한 문제이므로 chmod 755 /usr/share/nginx/html을 실행한 뒤 다시 시도해 보세요.
스케일링과 삭제 순서
StatefulSet은 늘릴 때와 줄일 때 순서가 반대입니다.
- 늘릴 때: 0부터 N-1까지 순서대로, 앞 파드가 Running·Ready가 된 다음에 다음 파드를 만듭니다.
- 줄일 때: N-1부터 0까지 거꾸로, 뒤 파드가 완전히 종료된 다음에 앞 파드를 종료합니다.
$ kubectl scale sts web --replicas=5
statefulset.apps/web scaled
# web-2, web-3, web-4 순서로 생성
$ kubectl patch sts web -p '{"spec":{"replicas":3}}'
statefulset.apps/web patched
# web-4, web-3 순서로 종료줄인 뒤에도 www-web-3, www-web-4 PVC는 남아 있습니다. 공식 문서는 데이터 안전이 자동 정리보다 더 중요하다는 이유로 스케일 다운과 StatefulSet 삭제 때 볼륨을 지우지 않는다고 설명합니다. 다시 늘리면 같은 이름의 파드가 같은 PVC를 이어서 씁니다.
병렬로 띄우고 싶다면
spec.podManagementPolicy로 순서 보장을 느슨하게 할 수 있습니다.
OrderedReady(기본): 위에서 본 대로 순서를 지킵니다.Parallel: 앞 파드를 기다리지 않고 모든 파드를 동시에 만들거나 종료합니다.
Parallel을 써도 이름과 스토리지의 정체성은 그대로 유지되고, 순서와 준비 대기만 사라집니다. 파드 사이의 시작 순서가 필요 없는 애플리케이션이라면 시작 시간을 줄일 수 있습니다.
업데이트 전략
spec.updateStrategy로 파드 템플릿(이미지, 리소스, 레이블 등)이 바뀔 때의 동작을 정합니다.
| 전략 | 동작 |
|---|---|
RollingUpdate (기본) | 큰 번호부터 한 번에 하나씩 지우고 다시 만듦. 새 파드가 Ready가 된 다음에 앞 번호로 진행 |
OnDelete | 자동으로 바꾸지 않음. 파드를 직접 지워야 새 템플릿으로 다시 만들어짐 |
롤링 업데이트는 삭제 순서와 같이 web-2 → web-1 → web-0 순으로 진행됩니다. 이미지를 바꿔 보고 진행 상황을 확인합니다.
$ kubectl patch statefulset web --type='json' -p='[{"op": "replace", "path": "/spec/template/spec/containers/0/image", "value":"registry.k8s.io/nginx-slim:0.24"}]'
statefulset.apps/web patched
$ kubectl rollout status sts/web
$ kubectl get pods -l app=nginx -o custom-columns=NAME:.metadata.name,IMAGE:.spec.containers[0].image
NAME IMAGE
web-0 registry.k8s.io/nginx-slim:0.24
web-1 registry.k8s.io/nginx-slim:0.24partition으로 일부만 먼저 업데이트하기
spec.updateStrategy.rollingUpdate.partition을 지정하면 순번이 partition 이상인 파드만 업데이트됩니다. 그보다 작은 순번의 파드는 템플릿이 바뀌어도 그대로이고, 도중에 지워져도 이전 버전으로 다시 만들어집니다. 카나리 배포나 단계적 배포에 쓸 수 있습니다.
# 순번 2 이상만 업데이트 대상 (replicas가 3이라면 web-2만)
$ kubectl patch statefulset web -p '{"spec":{"updateStrategy":{"type":"RollingUpdate","rollingUpdate":{"partition":2}}}}'
# 이미지를 바꾸면 web-2만 새 버전이 됩니다
# 문제가 없으면 partition을 0으로 낮춰 나머지도 진행
$ kubectl patch statefulset web -p '{"spec":{"updateStrategy":{"type":"RollingUpdate","rollingUpdate":{"partition":0}}}}'partition이 replicas보다 크면 템플릿을 바꿔도 어떤 파드에도 전달되지 않습니다. 업데이트를 잠시 막아 두는 용도로도 쓸 수 있습니다.
삭제할 때
StatefulSet을 지울 때는 두 가지 방식이 있습니다.
# 파드까지 같이 삭제 (기본)
$ kubectl delete statefulset web
# StatefulSet만 지우고 파드는 그대로 둠 (non-cascading)
$ kubectl delete statefulset web --cascade=orphan기억해 둘 것이 세 가지 있습니다.
- PVC는 둘 다 남습니다. 필요 없다면
kubectl delete pvc -l app=nginx로 직접 지워야 합니다. - Headless Service는 같이 지워지지 않습니다.
kubectl delete service nginx로 따로 지웁니다. - 공식 문서는 StatefulSet을 삭제할 때 파드가 순서대로 안전하게 종료되는 것을 보장하지 않는다고 설명합니다. 순서대로 종료하고 싶다면 삭제 전에
kubectl scale sts web --replicas=0으로 먼저 0까지 줄이세요.
PVC를 자동으로 정리하고 싶다면
spec.persistentVolumeClaimRetentionPolicy를 쓰면 삭제나 스케일 다운 때 PVC를 같이 지울지 정할 수 있습니다. 이 기능은 Kubernetes 1.32에서 stable이 되었습니다.
spec:
persistentVolumeClaimRetentionPolicy:
whenDeleted: Retain # StatefulSet을 삭제할 때
whenScaled: Delete # replicas를 줄일 때두 값 모두 기본은 Retain(지우지 않음)입니다. 이 정책은 StatefulSet이 파드를 삭제하거나 줄여서 없앨 때만 적용됩니다. 노드 장애로 파드가 사라지고 같은 이름의 파드가 다시 만들어지는 경우에는 PVC가 그대로 유지됩니다. Delete로 바꾸면 데이터가 사라지니 운영 데이터에는 신중하게 사용하세요.
주의할 점
1. 파드를 강제로 지우거나 terminationGracePeriodSeconds: 0을 쓰지 마세요.
StatefulSet은 같은 이름의 파드가 동시에 둘 이상 존재하지 않는 것을 전제로 합니다. 공식 문서는 terminationGracePeriodSeconds를 0으로 두는 것이 안전하지 않고 강력히 비권장이라고 설명합니다. 종료 유예 시간을 충분히 주는 방법은 아래 글에서 다뤘습니다.
2. 롤링 업데이트가 멈추면 템플릿만 되돌려서는 복구되지 않습니다.
기본 정책(OrderedReady)에서 새 템플릿의 파드가 영영 Ready가 되지 않으면 StatefulSet은 롤아웃을 멈추고 기다립니다. 템플릿을 정상 설정으로 되돌려도 이미 문제 있는 설정으로 만들어진 파드를 계속 기다리기 때문에, 되돌린 뒤에 그 파드를 직접 삭제해야 StatefulSet이 되돌린 템플릿으로 다시 만듭니다. 공식 문서에 알려진 문제(known issue)로 적혀 있습니다.
3. 파드 IP에 의존하지 마세요. 이름은 고정이지만 IP는 바뀝니다. 설정과 클라이언트는 DNS 이름을 사용합니다. 또한 파드가 막 만들어진 직후에는 앞서 실패한 조회 결과가 DNS에 캐시되어 이름이 바로 풀리지 않을 수 있습니다.
4. 스토리지는 자동으로 만들어지지 않는 환경이 있습니다. 동적 프로비저닝을 지원하는 StorageClass가 없으면 PVC가 Pending에 머물고 파드도 시작하지 못합니다. 이 경우 PersistentVolume을 미리 만들어 두어야 합니다.
5. replicas를 매니페스트와 수동 스케일로 같이 관리하지 마세요.
kubectl scale로 늘린 뒤 kubectl apply -f로 매니페스트를 다시 적용하면 매니페스트의 replicas 값으로 덮어써집니다. HPA 같은 자동 스케일러가 관리한다면 매니페스트에는 replicas를 적지 않습니다.
6. StatefulSet이 데이터베이스 운영을 대신해 주지는 않습니다. StatefulSet은 이름·순서·스토리지의 안정성을 보장할 뿐, primary 선출, 복제 설정, 백업 같은 애플리케이션 수준의 일은 하지 않습니다. 그래서 실무에서는 데이터베이스마다 제공되는 Operator나 Helm 차트를 함께 쓰는 경우가 많습니다. 또한 PVC 삭제는 곧 데이터 삭제이므로 백업은 별도로 준비해야 합니다.
정리
- StatefulSet은 파드마다 고정된 이름(순번), 고유한 DNS(Headless Service), **전용 스토리지(volumeClaimTemplates)**를 보장합니다.
- 기본은 0번부터 순서대로 만들고 큰 번호부터 지웁니다.
podManagementPolicy: Parallel로 순서 대기를 없앨 수 있습니다. - 업데이트는
RollingUpdate(큰 번호부터)와OnDelete가 있고,partition으로 일부만 먼저 올릴 수 있습니다. - 스케일 다운이나 삭제를 해도 PVC는 남습니다. 정리하려면 직접 지우거나
persistentVolumeClaimRetentionPolicy를 설정합니다. - 상태가 없는 앱이라면 Deployment가 더 단순합니다. StatefulSet은 안정적인 이름·순서·스토리지가 정말 필요할 때 선택하세요.