Feature Request: Support onDelete-like policy for Azure File share deletion behavior when reclaimPolicy=Delete

[fourhu]

Is your feature request related to a problem?/Why is this needed

Yes.

In Azure File CSI driver, when a dynamically provisioned PV is deleted with StorageClass.reclaimPolicy=Delete, users currently cannot configure a CSI-level deletion behavior (for example an onDelete-like policy used by some other NFS/SMB CSI drivers).
As a result, there is no built-in way to keep the underlying Azure File share for data preservation scenarios while still using the Delete reclaim workflow for Kubernetes resources.

This is needed for:

• safer production operations (avoid unintended data loss),
• migration/rollback workflows,
• better parity with user expectations from other file CSI ecosystems.

---

Describe the solution you'd like in detail

Add support for a StorageClass parameter (name can follow project conventions, e.g. onDelete) to control backend share behavior when PV deletion is triggered.

Suggested behavior:

• onDelete: delete (default, backward-compatible with current behavior)
• onDelete: retain (do not delete underlying Azure File share; only remove Kubernetes-side objects/attachments)

Implementation direction (high-level):

1. Parse the new parameter from StorageClass.
2. In controller DeleteVolume flow, branch deletion logic based on this parameter.
3. Keep default behavior unchanged when parameter is not set.
4. Add tests:
   • default path remains unchanged
   • retain path keeps the backend Azure File share after PV deletion
5. Document parameter usage and examples in driver docs.

---

Describe alternatives you've considered

1. Use reclaimPolicy: Retain at StorageClass/PV level.

   • This retains PV object semantics but does not provide CSI-level fine-grained delete behavior under Delete policy path.

2. Manual out-of-band protection (scripts/runbooks to snapshot or recreate shares).

   • Operationally complex, error-prone, and hard to standardize.

3. Admission/policy controls to block PVC/PV deletion in some namespaces.

   • Helps reduce accidents but does not solve storage-driver-level lifecycle control.

---

Additional context

• Repository: kubernetes-sigs/azurefile-csi-driver
• I can help validate behavior in AKS/Azure Kubernetes environments if a design/PR is proposed.
• If maintainers prefer a different parameter name/value convention, I’m happy to align and help test.

[andyzhangx]

there is DeleteRetentionPolicy (enabled by default), you could leverage this setting to recover data

[fourhu]

there is DeleteRetentionPolicy (enabled by default), you could leverage this setting to recover data

Thanks @andyzhangx for the response!

I understand that DeleteRetentionPolicy (enabled by default) provides account-level soft-delete protection and can help recover data after accidental deletion. That's a useful safety net.

However, after reviewing the source code more carefully, I realized our actual use case exposes a more fundamental issue that DeleteRetentionPolicy alone cannot address.

---

Our actual use case

We allocate one Azure File Share per app team (NFS protocol with encryptInTransit), and provision multiple PVCs on the same share using folderName (subDir) to isolate workloads:

One Azure File Share (NFS + encryptInTransit)
              │
  ┌───────────┼───────────┐
  │           │           │
subDir-A   subDir-B   subDir-C
(PVC-1)    (PVC-2)    (PVC-3)

With StorageClass.reclaimPolicy=Delete, we expect deleting PVC-1 to only clean up subDir-A. But the current implementation deletes the entire file share, destroying all other subdirectories and their data.

---

Root cause (from source code)

1. folderName is never encoded into volumeID:

// pkg/azurefile/azurefile.go
volumeIDTemplate = "%s#%s#%s#%s#%s#%s"
// rg # accountName # fileShareName # diskName # uuid # namespace
// folderName is completely absent

2. folderName is no-op at the controller layer:

// pkg/azurefile/controllerserver.go - CreateVolume parameter parsing
case folderNameField:
// no op, only used in NodeStageVolume

3. DeleteVolume always deletes the entire file share:

// pkg/azurefile/controllerserver.go
resourceGroupName, accountName, fileShareName, _, secretNamespace, subsID, err :=
    GetFileShareInfo(volumeID)
// folderName is not recoverable from volumeID at all

d.DeleteFileShare(ctx, subsID, resourceGroupName, accountName, fileShareName, ...)
// always deletes the whole share, regardless of folderName

So in a multi-PVC-per-share setup using folderName, deleting any one PVC will silently destroy all other PVCs' data on the same share — and while DeleteRetentionPolicy can help recover the share within the retention window, this still requires manual intervention and is not a scalable solution for production multi-tenant environments.

---

What we'd like to see

Support an onDelete StorageClass parameter to control deletion behavior when folderName is set:

onDelete value	Behavior
delete (default)	Delete only the subDir and its contents; delete whole share only when no folderName is set (backward-compatible)
retain	Keep the subDir and data intact; only release Kubernetes-side PV/PVC objects
archive	Rename the subDir (e.g. append timestamp) to preserve data while freeing the name

This pattern already exists in azureblob-csi-driver, so there is precedent within the same ecosystem.

We're happy to help validate this in AKS environments if there's interest in implementing it. Would love to hear maintainers' thoughts on the approach.

[fourhu]

Thinking about it more, maybe my use case is better suited for aznfs-csi-driver 😊

[andyzhangx]

I think you could use smb csi driver or nfs csi driver for such functionality?
the two drivers provides the onDelete parameter in storage class:
https://github.com/kubernetes-csi/csi-driver-smb
https://github.com/kubernetes-csi/csi-driver-nfs

I have also the owner of these two csi drivers, while I don't think we have plan to support onDelete for this azure file csi driver.