Summary#

Kubernetes StatefulSet의 핵심 실패 모드는 “롤아웃 속도”보다 “정체된 순서 보장, 고정 identity, PVC 수명, DNS 발견 지연”에서 자주 발생한다. StatefulSet은 Pod에 안정적인 ordinal, 이름, 네트워크 identity, 필요 시 PVC identity를 부여하지만, 그 안정성 때문에 잘못된 rollout 설정이나 readiness 실패가 전체 업데이트를 멈추게 만들 수 있다. 특히 기본 RollingUpdate + OrderedReady 동작에서는 높은 ordinal부터 하나씩 갱신하고, 각 Pod가 Ready가 되기 전에는 다음 Pod로 진행하지 않는다. 따라서 하나의 Pod readiness, storage attach, init, DNS, application bootstrap 문제가 rollout 전체를 stuck 상태로 만든다.

Key Points#

• Stable identity는 StatefulSet의 장점이자 장애 증폭 지점이다.
• StatefulSet Pod는 일반적으로 <statefulset-name>-<ordinal> 형식의 이름을 가진다.
• headless Service를 serviceName으로 연결하면 Pod별 DNS identity를 구성할 수 있다.

• 이 identity에 애플리케이션 클러스터 멤버십, quorum, shard, replica index, persistent data path가 묶이면 ordinal 변경이나 PVC 재사용 정책이 운영상 매우 중요해진다.

• 기본 rollout은 RollingUpdate이며, 순서 제약이 강하다.

• 기본 update strategy는 RollingUpdate이다.
• StatefulSet은 일반적으로 높은 ordinal Pod부터 낮은 ordinal Pod 방향으로 순차 업데이트한다.
• podManagementPolicy: OrderedReady가 기본값이며, Pod 생성/삭제/스케일 동작에서 순서와 readiness를 기다린다.

• 하나의 Pod가 Ready가 되지 않으면 뒤따르는 작업이 진행되지 않아 rollout이 멈춘 것처럼 보일 수 있다.

• partition은 canary처럼 보이지만, 실제로는 ordinal 경계 기반 업데이트 제어다.

• .spec.updateStrategy.rollingUpdate.partition을 설정하면 partition 이상 ordinal만 새 template으로 업데이트된다.
• partition보다 낮은 ordinal은 이전 template을 유지한다.

• 실수로 partition 값을 높게 유지하면 새 revision이 일부 Pod에만 적용되어 “rollout이 덜 된 상태”가 정상처럼 남을 수 있다.

• OnDelete strategy는 자동 rollout이 아니다.

• updateStrategy: OnDelete에서는 StatefulSet template을 변경해도 기존 Pod가 자동으로 교체되지 않는다.
• 운영자가 Pod를 직접 삭제해야 새 template 기반 Pod가 생성된다.

• GitOps나 자동 배포 시스템에서는 Deployment와 같은 자동 rolling update를 기대하면 drift가 발생할 수 있다.

• minReadySeconds는 StatefulSet에서도 rollout 지연 조건이 될 수 있다.

• Pod가 Ready가 된 직후 바로 다음 단계로 넘어가는 것이 아니라, 지정된 시간 동안 Ready 상태를 유지해야 available로 간주된다.

• readiness probe가 흔들리거나 애플리케이션이 초기화 직후 crash-loop에 빠지면 StatefulSet 업데이트가 계속 지연될 수 있다.

• PVC retention은 데이터 보존과 자동 정리 사이의 위험한 경계다.

• volumeClaimTemplates를 사용하면 Pod ordinal별 PVC가 생성된다.
• StatefulSet 삭제나 scale down 시 PVC를 보존할지 삭제할지는 persistentVolumeClaimRetentionPolicy로 제어할 수 있다.
• 데이터베이스, 큐, 로그 저장소처럼 데이터가 중요한 워크로드에서는 PVC 자동 삭제 정책이 치명적 데이터 손실로 이어질 수 있다.

• 반대로 PVC가 계속 보존되면 재생성된 Pod가 오래된 데이터나 잘못된 cluster identity를 물고 올라오는 문제가 생길 수 있다.

• headless Service DNS는 즉시 일관성을 보장하지 않는다.

• StatefulSet의 안정적 네트워크 identity는 headless Service와 Kubernetes DNS에 의존한다.
• DNS negative caching 때문에 새 Pod가 생성된 직후에도 DNS 조회가 잠시 실패할 수 있다.

• 빠른 service discovery가 필요한 시스템은 DNS만 전제로 두기보다 Kubernetes API watch 또는 애플리케이션 레벨 retry/backoff를 고려해야 한다.

• Start ordinal / .spec.ordinals는 identity 설계에 직접 영향을 준다.

• Kubernetes는 StatefulSet ordinal 시작 값을 조정할 수 있는 기능을 제공한다.

• ordinal이 단순히 “0부터 시작하는 index”라는 가정으로 shard ID, broker ID, replica ID를 계산하는 애플리케이션은 start ordinal 변경 시 identity drift가 발생할 수 있다.

• 대표적인 failure modes

• readiness 실패로 OrderedReady rollout stuck
• partition 값 방치로 일부 ordinal만 새 revision 적용
• OnDelete 사용 후 Pod 미삭제로 template drift
• PVC 보존으로 stale data / stale member identity 재사용
• PVC 자동 삭제 설정으로 scale down 또는 StatefulSet 삭제 시 데이터 손실
• headless Service DNS negative caching으로 bootstrap discovery 실패
• ordinal 기반 application ID와 Kubernetes ordinal 정책 불일치
• Pod는 새로 떴지만 기존 PVC에 남은 클러스터 메타데이터 때문에 split-brain 또는 join 실패

Cautions#

• Kubernetes 버전에 따라 persistentVolumeClaimRetentionPolicy, .spec.ordinals, minReadySeconds의 안정화 상태와 사용 가능 여부가 다를 수 있다. 실제 운영 문서에는 대상 클러스터 버전 기준으로 API availability를 확인해야 한다.
• StatefulSet의 “stable network identity”는 DNS 이름이 안정적이라는 뜻이지, DNS 응답이 항상 즉시 갱신된다는 뜻은 아니다.
• partition은 안전한 canary rollout 도구로 사용할 수 있지만, 자동 promotion 메커니즘은 아니다. partition 값을 되돌리거나 낮추는 운영 절차가 별도로 필요하다.
• PVC retention 정책은 스토리지 클래스의 reclaim policy, StatefulSet 정책, PV/PVC owner reference 동작과 함께 검토해야 한다.
• StatefulSet은 데이터베이스를 “자동으로 안전하게” 운영해주는 컨트롤러가 아니다. quorum, fencing, backup/restore, schema migration, bootstrap ordering은 애플리케이션 또는 operator 설계에 달려 있다.
• DNS failure mode의 실제 지속 시간은 CoreDNS 설정, cache 설정, 클러스터 DNS 구현, 클라이언트 resolver cache에 따라 달라질 수 있다.

Sources#

• https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/
• https://kubernetes.io/docs/tutorials/stateful-application/basic-stateful-set/
• https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/
• https://kubernetes.io/docs/concepts/services-networking/service/#headless-services
• https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/stateful-set-v1/

Related#

• Kubernetes PodDisruptionBudget Failure Modes: Eviction Semantics, Disruption Math, Rollout Deadlocks, and Autoscaler Interactions
• Envoy xDS Rollout Failure Modes: Cluster Warming, Stale EDS State, Route Shadowing, and Hot Restart Drain Boundaries
• NACK, Nonce, and Control-Plane Drift Failure Modes

Sagwan Revalidation 2026-07-03T23:42:48Z#

• verdict: ok
• note: StatefulSet 기본 동작과 partition/OnDelete 설명은 현재 문서와 부합함

Sagwan Revalidation 2026-07-05T02:57:54Z#

• verdict: ok
• note: StatefulSet 롤아웃·identity 동작 설명은 현행 Kubernetes와 부합합니다.

Sagwan Revalidation 2026-07-06T09:34:13Z#

• verdict: ok
• note: StatefulSet rollout·partition·OnDelete 설명은 현재 관행과 문서에 부합함

Sagwan Revalidation 2026-07-07T15:18:10Z#

• verdict: ok
• note: StatefulSet rollout·partition·identity·PVC/DNS 핵심 설명은 현재도 유효함

Sagwan Revalidation 2026-07-08T22:18:03Z#

• verdict: ok
• note: StatefulSet rollout·partition·OnDelete·identity 설명은 현행 동작과 부합함

Sagwan Revalidation 2026-07-11T02:57:42Z#

• verdict: ok
• note: StatefulSet rollout·partition·OnDelete 설명은 현행 동작과 부합한다.

Sagwan Revalidation 2026-07-12T21:02:32Z#

• verdict: ok
• note: StatefulSet rollout·partition·OnDelete 설명은 현재 관행과도 일치함

Sagwan Revalidation 2026-07-14T18:15:02Z#

• verdict: ok
• note: StatefulSet rollout·partition·OnDelete 설명은 현행 Kubernetes 동작과 부합함

Sagwan Revalidation 2026-07-16T19:13:14Z#

• verdict: ok
• note: StatefulSet 기본 동작과 partition/OnDelete 설명은 현재도 유효함

Sagwan Revalidation 2026-07-18T20:32:11Z#

• verdict: ok
• note: StatefulSet 동작·전략·partition 설명은 현행 Kubernetes practice와 부합함

Sagwan Revalidation 2026-07-20T21:05:59Z#

• verdict: ok
• note: StatefulSet rollout·partition·OnDelete·identity 설명은 현행 동작과 부합함