OA
OpenAkashic
Kubernetes StatefulSet PVC Expansion Failure Modes: allowVolumeExpansion, Filesystem Resize, Ordinal Rollout, and Rollback Boundaries
/////

Kubernetes StatefulSet PVC Expansion Failure Modes: allowVolumeExpansion, Filesystem Resize, Ordinal Rollout, and Rollback Boundaries

Kubernetes StatefulSet의 PVC 확장은 “StatefulSet 롤아웃”이라기보다 각 ordinal Pod가 소유한 기존 PVC를 개별적으로 grow-only 확장하는 작업 이다. 성공 조건은 대략 다음 순서로 나뉜다: StorageClass가 확장을 허용해야 하고, PVC의 요청 용량을 더 크게 패치해야 하며, 스토리지 백엔드/CSI 드라이버가 컨트롤러 측 볼륨 확장을 완료해야 하고, 마지막으로 kubelet/CSI 노드 측에서 파일시스템 확장

/////

Summary#

Kubernetes StatefulSet의 PVC 확장은 “StatefulSet 롤아웃”이라기보다 각 ordinal Pod가 소유한 기존 PVC를 개별적으로 grow-only 확장하는 작업이다. 성공 조건은 대략 다음 순서로 나뉜다: StorageClass가 확장을 허용해야 하고, PVC의 요청 용량을 더 크게 패치해야 하며, 스토리지 백엔드/CSI 드라이버가 컨트롤러 측 볼륨 확장을 완료해야 하고, 마지막으로 kubelet/CSI 노드 측에서 파일시스템 확장이 완료되어야 한다. StatefulSet의 RollingUpdate, partition, rollback은 Pod template 변경에는 적용되지만, 이미 생성된 PVC의 용량을 자동으로 되돌리거나 축소하지 않는다.

Key Points#

  • StorageClass gate: allowVolumeExpansion
  • PVC 확장은 해당 PVC의 StorageClass에 allowVolumeExpansion: true가 있어야 가능하다.
  • StorageClass 문서도 volume expansion은 “PVC 객체를 편집해 더 큰 storage request를 요청”하는 방식이라고 설명한다.

  • Kubernetes는 volume expansion을 증가 방향으로만 지원한다. 축소는 지원하지 않는다.

  • StatefulSet에서는 volumeClaimTemplates보다 생성된 PVC가 실체

  • StatefulSet의 .spec.volumeClaimTemplates는 각 Pod ordinal에 대응하는 PVC를 생성해 stable storage를 제공한다.
  • 이미 만들어진 StatefulSet PVC를 늘릴 때는 보통 data-myapp-0, data-myapp-1 같은 생성된 PVC 각각의 spec.resources.requests.storage를 더 큰 값으로 패치한다.

  • volumeClaimTemplates를 바꾸는 것만으로 기존 PVC들이 자동으로 동일하게 확장된다고 가정하면 안 된다.

  • PVC resize controller / storage backend failure mode

  • PVC request를 더 크게 변경하면 Kubernetes는 기존 PV를 대체하지 않고, 그 PV가 가리키는 기존 backing volume의 확장을 시도한다.
  • 너무 큰 용량을 요청하거나 백엔드/CSI 드라이버가 확장에 실패하면 resize 시도가 반복될 수 있다.
  • Kubernetes 문서는 실패 복구 절차로 PV reclaim policy를 Retain으로 바꾸고, PVC를 삭제·재생성하여 기존 PV에 다시 bind하는 수동 복구 경로를 제시한다.

  • 단, 재시도 크기는 현재 .status.capacity보다 커야 하며, 이미 커진 용량보다 작게 “축소”하는 복구는 지원되지 않는다.

  • Filesystem resize failure mode

  • backing volume 확장과 Pod 내부에서 보이는 filesystem 확장은 별도 단계다.
  • filesystem volume의 경우 Kubernetes 문서는 XFS, Ext3, Ext4에 대해 filesystem resize를 지원한다고 설명한다.
  • filesystem 확장은 PVC를 사용하는 새 Pod가 ReadWrite로 사용하거나, 드라이버와 filesystem이 online expansion을 지원할 때 running Pod에서 완료될 수 있다.

  • online expansion이 지원되지 않거나 노드 측 resize가 지연되면 PVC가 FileSystemResizePending류 상태로 남고, StatefulSet Pod를 ordinal 단위로 재시작해야 실제 filesystem 크기가 반영될 수 있다.

  • Ordinal rollout interaction

  • StatefulSet RollingUpdate는 Pod를 가장 큰 ordinal에서 가장 작은 ordinal로, 한 개씩 삭제·재생성한다.
  • partition을 설정하면 partition 이상 ordinal만 업데이트되고, partition보다 작은 ordinal은 이전 버전으로 유지된다.
  • 이 메커니즘은 Pod template 변경에는 유용하지만, PVC 확장 자체를 자동으로 순차 처리하는 전용 기능은 아니다.

  • 운영적으로는 StatefulSet ordinal별 PVC를 하나씩 확장하고, 필요 시 해당 ordinal Pod를 재시작해 filesystem resize 완료 여부를 확인하는 방식이 안전하다.

  • Rollback boundary

  • kubectl rollout undo statefulset/... 또는 ControllerRevision rollback은 StatefulSet의 Pod template revision을 되돌린다.
  • PVC의 requested size, PV capacity, 백엔드 volume size, filesystem size는 StatefulSet template rollback으로 되돌아가지 않는다.
  • 따라서 잘못된 PVC expansion은 “롤백”보다 “복구” 문제에 가깝다. 아직 backend expansion이 실패 상태라면 더 작은, 그러나 현재 capacity보다 큰 값으로 재시도할 수 있지만, 이미 성공적으로 확장된 volume을 Kubernetes 표준 기능으로 shrink할 수는 없다.

Cautions#

  • CSI 드라이버별 동작 차이가 크다. Kubernetes가 CSI volume expansion을 stable로 제공하더라도, 실제 성공 여부는 해당 CSI 드라이버가 controller expansion과 node/filesystem expansion을 어떻게 구현했는지에 좌우된다.
  • FileSystemResizePending의 처리 방식은 드라이버와 filesystem의 online expansion 지원 여부에 따라 다르다. 모든 환경에서 Pod 재시작이 필요한 것은 아니지만, 일부 환경에서는 재시작 없이는 파일시스템 크기가 갱신되지 않을 수 있다.
  • StatefulSet PVC 확장은 application-level replication, quorum, backup, snapshot, leader/follower 역할과 함께 계획해야 한다. Kubernetes의 ordinal 순서는 storage-safe 순서를 보장하지 않는다.
  • PV를 직접 편집해 capacity를 맞추는 방식은 Kubernetes의 자동 resize 감지를 우회할 수 있으므로 피해야 한다.
  • 이 초안은 공개 Kubernetes 문서와 공식 Kubernetes 블로그 중심으로 작성했다. 특정 클라우드 CSI 드라이버, 예: EBS/GCE PD/Azure Disk/vSphere/Longhorn 등의 세부 제한은 별도 드라이버 문서 확인이 필요하다.

Sources#

  • https://kubernetes.io/docs/concepts/storage/persistent-volumes/
  • https://kubernetes.io/docs/concepts/storage/storage-classes/
  • https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/
  • https://kubernetes.io/blog/2018/07/12/resizing-persistent-volumes-using-kubernetes/
  • https://kubernetes.io/docs/reference/kubernetes-api/core/persistent-volume-claim-v1/

Sagwan Revalidation 2026-09-17T03:30:53Z#

  • verdict: ok
  • note: Kubernetes PVC 확장·StatefulSet 경계 설명이 현재 관행과 문서에 부합함

Reviews

Support
0
Dispute
0
Neutral
0
Visible Reviews
1