PV Lifecycle CRDs

This kind configures PVC auto-expansion in CRD Mode. For feature concepts — threshold semantics, expansion methods, and StorageClass prerequisites — see Auto Expansion.

WavePvcAutoExpansion

WavePvcAutoExpansion declares auto-expansion policy for a single PVC — the usage threshold that triggers expansion, how much to expand, and an optional capacity ceiling.

Scope: namespaced — must be created in the same namespace as the target PVC.

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	—	Reference to the PVC to manage.
`targetRef.name`	string	Yes	—	Name of the PVC in the same namespace as the CR.
`thresholdPercentage`	number	Yes	—	Usage percentage (0–100) at which expansion is triggered. Wave expands the PVC when `used_bytes / capacity_bytes × 100 ≥ thresholdPercentage`.
`expansionPercentage`	number	No	—	Grow the PVC by this percentage of its current capacity on each trigger. Formula: `new_capacity = current_capacity × (1 + expansionPercentage / 100)`, where current capacity is the PVC's allocated storage (`spec.resources.requests.storage`). Example: 10 GiB + 50% → 15 GiB. Mutually exclusive with `expansionSizeByte` — exactly one must be set.
`expansionSizeByte`	number	No	—	Grow the PVC by this fixed number of raw bytes on each trigger. Example: `10737418240` = +10 GiB. In the Wave console, this field is entered in MiB — the console converts to bytes before saving (console 1024 MiB → `expansionSizeByte: 1073741824`). Mutually exclusive with `expansionPercentage` — exactly one must be set.
`maxCapacityBytes`	number	No	—	Optional hard ceiling in raw bytes. If the PVC's allocated storage is already at or above this value, Wave skips expansion entirely. If an expansion would overshoot this value, Wave clamps the expansion so the result equals exactly this ceiling. Omitted → no ceiling. Example: `107374182400` = 100 GiB. In the Wave console, this field is entered in MiB — the console converts to bytes before saving (console 102400 MiB → `maxCapacityBytes: 107374182400`).
`enabled`	boolean	No	`true`	Whether auto-expansion is active for this PVC. Set to `false` to pause expansion without deleting the CR.

⚠️

Exactly one expansion field is required. Setting both expansionPercentage and expansionSizeByte, or setting neither, causes Wave to report ValidationFailed in .status.conditions. The CR is accepted by kubectl apply (structural validation passes), but Wave refuses to write config until the violation is corrected.

Notes

Namespaced — create the CR in the namespace of the target PVC.
Exactly one expansion field. expansionPercentage and expansionSizeByte are mutually exclusive. Setting both, or omitting both, is caught by the Wave reconciler and reported as ValidationFailed. This is a runtime (semantic) check — kubectl apply will not reject it; the .status.conditions entry will.
StorageClass must allow expansion. The PVC's StorageClass must have allowVolumeExpansion: true. If it does not, Wave reports ReconcileError in .status.conditions — the CR was accepted structurally but cannot be reconciled. To recover, either update the StorageClass or retarget the CR at a PVC backed by an expandable StorageClass.
TargetNotFound self-heals. A CR whose target PVC does not exist yet succeeds at kubectl apply time. Wave reports TargetNotFound in .status.conditions and reconciles automatically when the PVC appears. Apply order does not matter.
enabled defaults to true. Omitting the field leaves auto-expansion active. Set enabled: false to pause expansion for a PVC without removing the CR.
Deleting the CR removes the expansion policy. Wave stops monitoring the PVC for auto-expansion. No in-progress Kubernetes volume expansion is cancelled — those complete independently through the Kubernetes volume controller.

Unused PV Detection Overview