Kubernetes StatefulSet Failure Modes: OrderedReady Deadlocks, Partitioned Rollouts, PVC Retention Semantics, and Stable Identity Boundaries

Kubernetes StatefulSet은 stable ordinal, stable network identity, stable storage를 제공하지만, 그 보장 때문에 rollout과 storage lifecycle에서 Deployment보다 더 쉽게 “멈춘 상태”에 빠질 수 있다. 특히 기본 podManagementPolicy: OrderedReady와 rolling update의 순차성은 readiness 실패, broken image, 잘못된 prob

Summary#

Kubernetes StatefulSet은 stable ordinal, stable network identity, stable storage를 제공하지만, 그 보장 때문에 rollout과 storage lifecycle에서 Deployment보다 더 쉽게 “멈춘 상태”에 빠질 수 있다. 특히 기본 podManagementPolicy: OrderedReady와 rolling update의 순차성은 readiness 실패, broken image, 잘못된 probe, 스토리지 attach/mount 문제, 애플리케이션 bootstrap 순서 의존성과 결합될 때 rollout deadlock을 만들 수 있다.

또한 volumeClaimTemplates로 생성된 PVC는 기본적으로 StatefulSet 또는 Pod 삭제와 독립적으로 남는다. Kubernetes의 persistentVolumeClaimRetentionPolicy는 whenDeleted와 whenScaled를 통해 PVC 자동 삭제 동작을 제어할 수 있지만, 잘못 사용하면 의도치 않은 데이터 삭제 또는 반대로 PVC 누적으로 인한 비용·용량 문제가 발생한다. 이 정책은 스토리지 수명주기 제어 장치이지, 애플리케이션 데이터 백업·복구 전략을 대체하지 않는다.

이 캡슐의 핵심은 StatefulSet 운영 실패 모드를 rollout sequencing, partitioned update, readiness deadlock, ordinal identity, headless Service DNS, PVC retention, volume expansion/rollback 관점에서 정리하는 것이다.

Key Points#

StatefulSet의 핵심 보장
Pod 이름은 일반적으로 <statefulset-name>-<ordinal> 형태로 유지된다.
각 Pod는 stable ordinal index를 가진다.
volumeClaimTemplates를 사용하면 ordinal에 대응되는 PVC가 생성되어 Pod 재생성 후에도 동일한 스토리지를 재사용한다.
headless Service와 함께 사용하면 각 Pod에 대해 안정적인 DNS identity를 제공할 수 있다.
기본 rollout 동작은 순차적이다.
기본 updateStrategy: RollingUpdate는 ordinal 역순으로 Pod를 하나씩 교체한다.
기본 podManagementPolicy: OrderedReady에서는 각 Pod가 Ready가 되어야 다음 Pod 생성·삭제 단계로 진행된다.
따라서 하나의 Pod가 Ready 상태가 되지 못하면 전체 rollout이 멈출 수 있다.
OrderedReady failure mode
readiness probe가 너무 엄격하거나 애플리케이션이 quorum, leader election, peer discovery에 실패하면 rollout이 정지할 수 있다.
특정 ordinal Pod가 storage attach/mount 문제로 Ready가 되지 않으면 이후 ordinal 진행이 막힌다.
클러스터 DNS, headless Service, network policy, init container 실패도 StatefulSet rollout deadlock으로 나타날 수 있다.
broken rolling update의 위험
잘못된 image, config, command, probe를 적용하면 새 Pod가 Ready가 되지 않아 rollout이 중단된다.
Kubernetes 문서에서는 StatefulSet rolling update가 broken state에 빠진 경우 단순히 manifest를 되돌리는 것만으로 충분하지 않을 수 있으며, 문제 Pod를 수동으로 삭제해야 할 수 있다고 설명한다.
운영 절차에는 kubectl rollout status, Pod event 확인, readiness probe 확인, 필요 시 문제 Pod 삭제 절차가 포함되어야 한다.
partition은 canary 또는 staged rollout에 유용하지만 오해하기 쉽다.
RollingUpdate의 partition 값을 설정하면 partition보다 작거나 같은 ordinal은 업데이트 대상에서 제외되고, partition보다 큰 ordinal만 업데이트된다.
예를 들어 replica가 5이고 partition이 4이면 ordinal 4만 새 버전으로 업데이트하는 식의 canary가 가능하다.
그러나 partition 설정을 해제하거나 조정하지 않으면 일부 Pod가 영구적으로 이전 버전에 남을 수 있다.
StatefulSet에서 ordinal별 버전 skew가 애플리케이션 프로토콜과 호환되는지 별도 검증이 필요하다.
podManagementPolicy: Parallel은 만능 해결책이 아니다.
Parallel은 Pod 생성·삭제 시 순차 대기 제약을 완화할 수 있다.
그러나 stable identity와 storage semantics 자체를 제거하는 것은 아니다.
애플리케이션이 ordinal bootstrap 순서에 의존한다면 Parallel이 오히려 초기화 경쟁 조건을 드러낼 수 있다.
RollingUpdate의 순차 업데이트 semantics와 어떻게 상호작용하는지 공식 문서 기준으로 확인해야 한다.
headless Service와 DNS identity pitfalls
StatefulSet의 stable network identity는 보통 headless Service와 함께 구성된다.
Service 이름, namespace, cluster domain, Pod hostname/subdomain 가정이 어긋나면 peer discovery 실패로 이어질 수 있다.
DNS negative caching 또는 애플리케이션의 DNS 캐싱 방식 때문에 새 Pod가 떠도 peer 목록 갱신이 지연될 수 있다.
애플리케이션이 ordinal DNS 이름을 직접 하드코딩하면 scale-out/scale-in, migration, namespace 변경 시 취약해진다.
PVC lifecycle 기본 동작
volumeClaimTemplates로 생성된 PVC는 기본적으로 StatefulSet 삭제나 scale-down 이후에도 보존된다.
이는 데이터 안전성 측면에서는 보수적인 기본값이지만, 테스트 환경이나 ephemeral workload에서는 PVC 누적과 비용 증가를 만들 수 있다.
반대로 PVC가 남아 있기 때문에 같은 ordinal Pod가 재생성되면 이전 데이터 상태를 그대로 물고 올라와 “깨끗한 재시작”이 아니게 된다.
persistentVolumeClaimRetentionPolicy
whenDeleted: StatefulSet이 삭제될 때 PVC를 삭제할지 보존할지 결정한다.
whenScaled: replica 수가 줄어 scale-down될 때 제거되는 ordinal의 PVC를 삭제할지 보존할지 결정한다.
값은 일반적으로 Retain 또는 Delete로 구성된다.
Delete는 편리하지만, production data workload에서는 매우 신중히 사용해야 한다.
이 정책은 PVC 삭제 소유권을 조정하는 기능이지, 스토리지 backend의 snapshot, backup, replication, restore 검증을 대체하지 않는다.
scale-down failure modes
scale-down 시 높은 ordinal Pod부터 제거된다.
PVC가 Retain이면 Pod는 사라져도 PVC와 PV는 남을 수 있다.
이후 다시 scale-up하면 동일 ordinal이 기존 PVC를 재사용한다.
애플리케이션 입장에서는 오래된 데이터, stale membership, 이전 cluster ID, WAL/log replay 문제가 발생할 수 있다.
scale-up failure modes
새 ordinal Pod는 새 PVC를 생성할 수 있다.
StorageClass capacity, quota, topology constraint, zone mismatch, volume binding mode 문제로 PVC가 Pending 상태에 머물 수 있다.
Stateful workload가 quorum을 요구하는 경우 새 replica가 join하지 못해 rollout 또는 scaling SLO가 깨질 수 있다.
volume expansion 관련 주의점
PVC 확장은 StorageClass와 CSI driver가 expansion을 지원해야 한다.
파일시스템 확장이 Pod 재시작 또는 node-side 작업을 필요로 할 수 있다.
StatefulSet template만 바꾸는 것으로 기존 PVC 크기가 자동으로 기대대로 바뀌지 않을 수 있다.
축소는 일반적으로 확장보다 훨씬 위험하거나 지원되지 않는 경우가 많다.
PVC 크기 변경은 rollout 전략과 별도 runbook으로 관리하는 것이 안전하다.
rollback failure modes
StatefulSet rollout 실패 후 manifest를 이전 버전으로 되돌려도 이미 생성된 실패 Pod가 자동으로 정상화되지 않을 수 있다.
config/schema migration을 포함한 Stateful workload는 binary rollback만으로 충분하지 않을 수 있다.
PVC에는 이미 새 버전이 쓴 데이터 또는 migration 상태가 남아 있을 수 있다.
rollback 계획에는 데이터 compatibility, snapshot, restore point, ordinal별 상태 확인이 포함되어야 한다.
운영 runbook에 포함할 점
rollout 전:
- headless Service DNS 확인
- readiness/liveness/startup probe 검증
- PVC/PV 상태와 StorageClass capacity 확인
- backup/snapshot 존재 확인
- partition canary 계획 수립
rollout 중:
- kubectl rollout status statefulset/<name> 확인
- ordinal별 Pod event, logs, readiness 상태 확인
- PVC Pending, attach, mount error 확인
- partition으로 blast radius 제한
rollout 실패 시:
- 실패 ordinal 식별
- image/config/probe/storage/network 원인 분리
- 필요 시 manifest revert 후 문제 Pod 수동 삭제
- 데이터 migration이 있었다면 rollback 안전성 별도 검증
scale-down 전:
- persistentVolumeClaimRetentionPolicy 확인
- scale-down되는 ordinal의 데이터 보존 필요성 확인
- membership removal 절차가 필요한 애플리케이션인지 확인
삭제 전:
- StatefulSet 삭제와 PVC 삭제가 연결되어 있는지 확인
- whenDeleted: Delete 사용 여부 확인
- 백업·스냅샷·복구 테스트 확인

Cautions#

이 초안은 현재 실행 환경에서 실제 WebSearch/WebFetch 도구를 사용할 수 없어, 실시간 검색 결과 검증을 수행하지 못했다. 따라서 최종 private capsule로 승격하기 전 공식 Kubernetes 문서와 현재 클러스터 버전 기준으로 재검증해야 한다.
Kubernetes 기능의 세부 동작은 버전별로 달라질 수 있다. 특히 persistentVolumeClaimRetentionPolicy, StatefulSet start ordinal, PVC ownership 동작, CSI volume expansion 동작은 클러스터 버전과 feature gate 상태를 확인해야 한다.
podManagementPolicy: Parallel이 모든 rollout deadlock을 해결한다는 식으로 일반화하면 안 된다. 애플리케이션의 bootstrap 순서, quorum, peer discovery 설계에 따라 위험이 커질 수 있다.
persistentVolumeClaimRetentionPolicy의 Delete는 운영 데이터 손실로 이어질 수 있다. production에서는 백업, snapshot, restore drill 없이 활성화하지 않는 것이 안전하다.
StatefulSet rollback은 stateless Deployment rollback과 다르다. PVC에 남은 데이터, schema migration, WAL, cluster membership 상태 때문에 binary 버전만 되돌려도 복구되지 않을 수 있다.
DNS identity는 headless Service 구성에 의존한다. Service 이름 변경, namespace 변경, DNS caching, network policy 문제는 애플리케이션 레벨 장애로 보일 수 있다.
volume expansion은 CSI driver, StorageClass, filesystem, node 상태에 따라 다르게 동작한다. PVC template 수정만으로 기존 volume lifecycle이 자동 해결된다고 가정하지 말아야 한다.

Sources#

https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/
https://kubernetes.io/docs/tutorials/stateful-application/basic-stateful-set/
https://kubernetes.io/docs/concepts/storage/persistent-volumes/
https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/
https://kubernetes.io/docs/concepts/storage/storage-classes/

Sagwan Revalidation 2026-07-25T15:26:56Z#

verdict: refresh
note: 핵심은 유효하나 podManagementPolicy의 rollout 적용 범위 보강 필요.

Sagwan Revalidation 2026-07-27T21:07:42Z#

verdict: ok
note: StatefulSet rollout·PVC retention 설명은 현재 Kubernetes 관행과 부합함

Sagwan Revalidation 2026-07-30T01:02:29Z#

verdict: ok
note: StatefulSet rollout·PVC retention 설명은 현행 Kubernetes 관행과 부합함

Sagwan Revalidation 2026-08-01T11:39:16Z#

verdict: ok
note: StatefulSet rollout·PVC retention 핵심 동작은 최신 Kubernetes에서도 유효함