Support symlinks for Filesystem mode local volumes to avoid nested mount issues

[Copilot]

Nested mount points under local PV paths prevent kubelet from unmounting volumes, causing Pod termination failures. This adds symlink support for Filesystem mode volumes, allowing the provisioner to resolve symlinks to their mount point targets and use those paths in PV specs.

Changes

Volume discovery

• IsLikelyMountPoint now accepts symlinks pointing to mount points (Linux) in addition to direct mount points
• Discovery logic resolves symlinks and stores target paths as PV HostPath
• Windows implementation already required symlinks; added documentation clarifying platform differences

Documentation

• New operations guide section recommending symlinks over bind mounts for Filesystem volumes
• Example workflow: mount disk outside discovery directory, symlink into it

Example

Current approach (bind mount):

mount /dev/sda1 /mnt/disk-uuid
mkdir /mnt/disks/disk-uuid
mount --bind /mnt/disk-uuid /mnt/disks/disk-uuid  # Creates nested mount

Recommended approach (symlink):

mount /dev/sda1 /mnt/disk-uuid
ln -s /mnt/disk-uuid /mnt/disks/disk-uuid  # Provisioner resolves to /mnt/disk-uuid

PV will reference /mnt/disk-uuid directly, avoiding mount point nesting under kubelet's volume paths.

Backward compatibility

Direct mount points in the discovery directory continue to work unchanged.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• get.helm.sh
  • Triggering command: /usr/bin/curl curl -s REDACTED ux_amd64/vet -v sioner/sig-storage-local-static--c=4 cal-static-provisioner/sig-stora-nolocalimports ux_amd64/vet cation/request/w/opt/hostedtoolcache/go/1.24.11/x64/pkg/tool/linux_amd64/vet g x64/pkg/tool/lin/tmp/go-build3579612690/b1513/vet.cfg ux_amd64/vet -v sioner/sig-storage-local-static-provisioner/vendor/k8s.io/kubernetes/pkg/scheduler/framework/cycgit sioner/sig-storage-local-static-provisioner/vendor/k8s.io/kubernetes/pkg/scheduler/framework/evefor-each-ref ux_amd64/vet errors/doc.go errors/storage.g-v x64/pkg/tool/lin/tmp/go-build3579612690/b1631/vet.cfg ux_amd64/vet (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Bug Report: Nested mountpoints causes failure when using filesystem mode local PVs</issue_title>
<issue_description>What happened

When using a StorageClass with the local-static-provisioner and volumeMode: Filesystem, the provisioner creates mount points under:

/var/lib/kubelet/pods/<pod-uid>/volumes/kubernetes.io~local-volume/<volume-name>

If the underlying filesystem already contains older or nested mount points:

• Existing (older) mount points become inaccessible from the Pod.
• Newly created nested mount points cause the kubelet to fail during unmount or detach operations, preventing the Pod from terminating cleanly.

What you expected to happen

Local PersistentVolumes provisioned with volumeMode: Filesystem should:

• Use isolated or predictable mount locations that avoid nesting mount points. (by using symlink)
• Properly unmount and clean up all filesystem mount points when Pods terminate.

How to reproduce it

1. Deploy a Pod that uses a Local PV provisioned via a StorageClass configured for the local-static-provisioner.

2. Ensure the PV path includes a mount point created using --bind.

3. Confirm the mount point is accessible from within the Pod.

4. On the node, create a new nested bind mount under the same path.

5. Delete the Pod.

6. Observe that the unmount operation fails. The kubelet logs show errors similar to:

   umount: /var/lib/kubelet/pods/<pod-uid>/volumes/kubernetes.io~local-volume/<volume-name>: target is busy
   

Anything else we need to know

This issue results in stale mounts under /var/lib/kubelet/pods, blocking pod cleanup and re-scheduling.

Environment

• Kubernetes version: v1.29
• OS: AL2023
• Kernel: 6.12.40-64.114.amzn2023.x86_64</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Bug Report: Nested mountpoints causes failure when using filesystem mode local PVs #517

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[k8s-ci-robot]

Hi @Copilot. Thanks for your PR.

I'm waiting for a github.com member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: Copilot
Once this PR has been reviewed and has the lgtm label, please ask for approval from andyzhangx. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment