PV Lifecycle CRD

이 kind는 CRD Mode에서 PVC auto-expansion을 설정합니다. 임계값 의미, 확장 방식, StorageClass 사전 요구사항 등 기능 개념은 Auto Expansion 문서를 참고하세요.

WavePvcAutoExpansion

WavePvcAutoExpansion은 하나의 PVC에 대한 auto-expansion 정책을 선언합니다. 확장을 트리거하는 사용률 임계값, 확장 크기, 선택적인 용량 상한을 정의합니다.

Scope: namespaced. 대상 PVC와 같은 namespace에 생성해야 합니다.

apiVersion: wavek8s.com/v1alpha1
kind: WavePvcAutoExpansion
metadata:
  name: data-pvc-expansion
  namespace: prod
spec:
  targetRef:
    name: data-pvc            # PVC name in the same namespace as this CR
  thresholdPercentage: 80     # expand when usage reaches 80% of current capacity
  expansionPercentage: 50     # grow by 50% of current size on each trigger
  # expansionSizeByte: 10737418240  # alternative: fixed +10 GiB per trigger (mutually exclusive with expansionPercentage)
  maxCapacityBytes: 107374182400   # hard ceiling: 100 GiB (optional)
  enabled: true               # default true; set false to pause without deleting

Spec fields

Field	Type	Required	Default	Description
`targetRef`	object	Yes	-	관리할 PVC에 대한 참조입니다.
`targetRef.name`	string	Yes	-	CR과 같은 namespace에 있는 PVC의 이름입니다.
`thresholdPercentage`	number	Yes	-	확장을 트리거하는 사용률(%, 0~100)입니다. `used_bytes / capacity_bytes × 100 ≥ thresholdPercentage`이면 Wave가 PVC를 확장합니다.
`expansionPercentage`	number	No	-	트리거될 때마다 현재 용량의 이 퍼센트만큼 PVC를 확장합니다. 공식: `new_capacity = current_capacity × (1 + expansionPercentage / 100)` (여기서 현재 용량은 PVC에 할당된 스토리지, 즉 `spec.resources.requests.storage`입니다). 예: 10 GiB + 50% → 15 GiB. `expansionSizeByte`와는 함께 설정할 수 없으며 둘 중 정확히 하나만 설정해야 합니다.
`expansionSizeByte`	number	No	-	트리거될 때마다 이 고정 바이트 수만큼 PVC를 확장합니다. 예: `10737418240` = +10 GiB. Wave 콘솔에서는 이 필드를 MiB 단위로 입력하며, 저장 전에 콘솔이 바이트 값으로 변환합니다 (콘솔 1024 MiB → `expansionSizeByte: 1073741824`). `expansionPercentage`와는 함께 설정할 수 없으며 둘 중 정확히 하나만 설정해야 합니다.
`maxCapacityBytes`	number	No	-	바이트 단위의 선택적 상한선입니다. PVC에 이미 할당된 스토리지가 이 값 이상이면 Wave는 확장을 아예 건너뜁니다. 확장 결과가 이 값을 초과하게 되면 Wave는 결과가 정확히 이 상한값과 같아지도록 확장량을 조정(clamp)합니다. 생략하면 상한이 없습니다. 예: `107374182400` = 100 GiB. Wave 콘솔에서는 이 필드를 MiB 단위로 입력하며, 저장 전에 콘솔이 바이트 값으로 변환합니다 (콘솔 102400 MiB → `maxCapacityBytes: 107374182400`).
`enabled`	boolean	No	`true`	해당 PVC에 대해 auto-expansion이 활성화되어 있는지 여부입니다. CR을 삭제하지 않고 확장을 일시 중지하려면 `false`로 설정하세요.

⚠️

확장 필드는 정확히 하나만 설정해야 합니다. expansionPercentage와 expansionSizeByte를 둘 다 설정하거나 둘 다 설정하지 않으면 Wave가 .status.conditions에 ValidationFailed를 보고합니다. CR 자체는 kubectl apply로 정상 등록되지만 (구조적 검증은 통과), 이 문제를 해결하기 전까지 Wave는 설정을 반영하지 않습니다.

Notes

Namespaced: 대상 PVC의 namespace에 CR을 생성하세요.
확장 필드는 하나만 설정합니다. expansionPercentage와 expansionSizeByte는 함께 설정할 수 없습니다. 둘 다 설정하거나 둘 다 생략하면 Wave reconciler가 이를 감지해 ValidationFailed로 보고합니다. 이는 런타임(semantic) 검증이므로 kubectl apply 단계에서는 거부되지 않고, .status.conditions 항목에서 확인됩니다.
StorageClass가 확장을 허용해야 합니다. PVC의 StorageClass에는 allowVolumeExpansion: true가 설정되어 있어야 합니다. 설정되어 있지 않으면 Wave가 .status.conditions에 ReconcileError를 보고합니다. CR은 구조적으로는 등록되었지만 reconcile할 수 없는 상태입니다. 해결하려면 StorageClass를 수정하거나, 확장 가능한 StorageClass를 사용하는 PVC로 CR의 대상을 변경하세요.
TargetNotFound은 자동으로 해소됩니다. 대상 PVC가 아직 없어도 kubectl apply는 성공합니다. Wave는 .status.conditions에 TargetNotFound를 보고하며, 이후 PVC가 생성되면 자동으로 reconcile합니다. 적용 순서는 상관없습니다.
enabled의 기본값은 true입니다. 필드를 생략하면 auto-expansion이 계속 활성화된 상태로 유지됩니다. CR을 제거하지 않고 특정 PVC의 확장만 멈추려면 enabled: false로 설정하세요.
CR을 삭제하면 확장 정책이 제거됩니다. Wave는 해당 PVC에 대한 auto-expansion 모니터링을 중단합니다. 이미 진행 중인 Kubernetes 볼륨 확장은 취소되지 않으며, Kubernetes 볼륨 컨트롤러를 통해 독립적으로 완료됩니다.

미사용 PV 감지 개요