NFS as Kubernetes Persistent Storage

By Khimananda Oli | Last reviewed: August 2026

NFS as Kubernetes Persistent Storage remains a pragmatic choice for teams needing shared, read-write-many (RWX) volumes without the complexity of distributed block storage. While cloud-native CSI drivers like EBS or Ceph RBD dominate high-performance database workloads, NFS provides a lightweight, protocol-native solution for configuration sharing, media assets, and legacy application migration. This guide covers the exact configuration, security hardening, and operational guardrails required to run NFS reliably in production clusters.

How do you configure NFS as Kubernetes Persistent Storage?

The most reliable approach treats the NFS backend as infrastructure, not an afterthought. Before writing any YAML, verify that every cluster node has the nfs-common (Debian/Ubuntu) or nfs-utils (RHEL/CentOS) package installed. Missing client utilities are the single most frequent cause of ContainerCreating hangs when using Kubernetes persistent volumes and storage. Once prerequisites are met, define the storage layer declaratively.

Create the PersistentVolume definition

Static provisioning gives you explicit control over server IPs, paths, and mount options. This is preferred for compliance-sensitive environments where audit trails must map specific volumes to specific backends.

<!-- nfs-pv.yaml -->
apiVersion: v1
kind: PersistentVolume
metadata:
  name: nfs-shared-assets
  labels:
    type: nfs
    app: media-assets
spec:
  capacity:
    storage: 500Gi
  accessModes:
    - ReadWriteMany
    - ReadOnlyMany
  persistentVolumeReclaimPolicy: Retain
  mountOptions:
    - nfsvers=4.2
    - rsize=1048576
    - wsize=1048576
    - hard
    - timeo=600
    - retrans=2
    - noatime
  nfs:
    server: 10.0.1.50
    path: /srv/nfs/k8s-media

Bind with a PersistentVolumeClaim

The PVC requests storage by label selector rather than size alone. This prevents accidental binding to unrelated NFS volumes in multi-tenant clusters.

<!-- nfs-pvc.yaml -->
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: media-assets-pvc
  namespace: content-platform
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 500Gi
  selector:
    matchLabels:
      type: nfs
      app: media-assets

Mount in your workload

Always set readOnly explicitly when the workload does not need write access. This reduces the blast radius of a compromised container and aligns with least-privilege principles I apply across SOC 2 engagements.

volumeMounts:
  - name: media-store
    mountPath: /app/data/media
    readOnly: false
volumes:
  - name: media-store
    persistentVolumeClaim:
      claimName: media-assets-pvc

What are the security best practices for NFS in Kubernetes?

NFS was designed for trusted LANs, not zero-trust cloud networks. Running it securely requires compensating controls at every layer. In my experience auditing Nepal-based fintech and global SaaS platforms, these five practices prevent the majority of NFS-related incidents.

• Restrict exports by CIDR, never wildcard. Use /srv/nfs/k8s-data 10.0.0.0/24(rw,sync,no_subtree_check,root_squash). Never use * or 0.0.0.0/0.
• Enforce root_squash universally. Map root to nobody to prevent container escape via UID 0. Only disable for specific service accounts with documented justification.
• Isolate on a dedicated VLAN or subnet. NFS traffic should never traverse the same network as public ingress or management planes. Use Kubernetes network policies to restrict pod-to-NFS communication to only namespaces that require it.
• Encrypt in transit for cross-zone or hybrid setups. Use NFSv4.2 with Kerberos (krb5p) or tunnel through WireGuard/IPsec. Plain NFS over the open internet is unacceptable for any regulated workload.
• Audit export access logs. Enable nfsd logging and forward to your centralized stack. Correlate mount events with pod scheduling logs for forensic readiness. See structured logging best practices for schema guidance.

When should you use NFS versus CSI drivers like Longhorn or RBD?

Choosing between NFS and block-based CSI drivers is an architectural decision, not a preference. Each has failure modes that matter differently depending on your workload profile. The table below reflects real trade-offs observed across production clusters in 2026.

If your workload requires sub-millisecond latency or strong consistency guarantees, skip NFS entirely and evaluate Longhorn distributed storage for Kubernetes or your cloud provider’s managed block service. NFS excels when multiple pods must read and write the same files concurrently, and when operational simplicity outweighs raw throughput.

How do you troubleshoot NFS mount failures in Kubernetes?

NFS issues manifest as pods stuck in ContainerCreating, CrashLoopBackOff after mount timeouts, or silent data corruption. Follow this ordered diagnostic sequence before restarting services or redeploying.

1. Verify node-level connectivity first. SSH into the affected node and run showmount -e 10.0.1.50. If this fails, the problem is network/firewall/export config — not Kubernetes. Check nfs-client installation and kernel module status (lsmod | grep nfs).
2. Inspect kubelet logs for mount errors. Run journalctl -u kubelet --since "1 hour ago" | grep -i nfs. Look for mount.nfs: access denied (export permissions), server not responding (network/timeout), or stale file handle (server rebooted without client remount).
3. Validate PV/PVC binding status. Use kubectl get pv,pvc -A. A PVC in Pending with no matching PV indicates label mismatch or capacity discrepancy. A PV in Available but unbound suggests access mode incompatibility.
4. Test mount manually with identical options. Copy the mountOptions from your PV spec and run mount -t nfs -o nfsvers=4.2,rsize=1048576,wsize=1048576,hard,timeo=600 10.0.1.50:/srv/nfs/k8s-media /mnt/test. This isolates whether the issue is Kubernetes-specific or fundamental to the NFS configuration.
5. Check for UID/GID mismatches. Containers running as non-root may lack write permissions if the NFS export directory ownership doesn’t match the pod’s runAsUser. Set consistent ownership on the server: chown -R 1000:1000 /srv/nfs/k8s-media and enforce securityContext.runAsUser: 1000 in your pod spec.

A common mistake is relying on soft mounts to avoid hangs. Soft mounts return I/O errors to the application instead of retrying, which causes silent data loss in write-heavy workloads. Always use hard mounts with appropriate timeo and retrans values unless your application explicitly handles partial writes and has its own retry logic.

Practical Next Steps for Production NFS Deployments

NFS as Kubernetes Persistent Storage works reliably when treated as a first-class infrastructure component with defined ownership, monitoring, and change control. Start by documenting your NFS server lifecycle: who owns patching, how exports are version-controlled, and what the failover procedure is if the primary server dies. Automate client package installation across nodes using your existing configuration management — manual installs drift and cause outages during scale-up events. Implement mount option standards as OPA policies or admission webhooks to prevent developers from accidentally deploying soft mounts or insecure versions. Finally, integrate NFS metrics into your observability stack; track nfsstat counters, mount latency percentiles, and export utilization alongside your application SLOs. If your team needs help designing a compliant, auditable storage layer that balances developer velocity with operational safety, reach out to discuss your architecture.