Don't miss out on new posts! Sign up! Also, visit the VHT Forums!

NFS Subdir External Provisioner: Connect Your NAS with Kubernetes

One of the cool things I have done recently in the lab is working with shared storage class configurations with Kubernetes persistent volumes. I recently set up an NFS share on my Synology NAS device and used the nfs-subdir-external-provisioner to add persistent shared storage to the cluster for spinning up storage for my apps. Let’s look at how to set up an NFS share, and install the nfs-subdir-external-provisioner.

What is the nfs-subdir-external-provisioner?

The NFS subdir external provisioner serves as an automated provisioner that leverages your pre-configured NFS server to allow you to support dynamic provisioning of Kubernetes Persistent Volumes through Persistent Volume Claims. The naming convention for the provisioned persistent volumes follows the format: ${namespace}-${pvcName}-${pvName}.

Basically, the boiled-down version is the NFS subdir external provisioner, which allows you to connect your Kubernetes cluster to NFS persistent storage. It sets up a storage class that provides automatic storage provisioning for your Kubernetes pods.

NFS storage and Kubernetes

For Kubernetes clusters, NFS storage is a great solution for persistent volumes. NFS allows multiple pods to access the storage at the same time and access the same data. This is important since you want to make sure all your hosts and pods can access the data for failover scenarios.

NFS is a protocol that has been around for a long while and is likely found in many environments, meaning you won’t have to set up a new kind of storage just for Kubernetes. You can make use of what you already have.

Setup an NFS share in Synology

While I will show the steps in Synology, the general steps will work with other NFS server types. In the home lab, I currently have the Synology NAS device as my main NAS storage. Let’s look at setting up the NFS share for Kubernetes.

Enable NFS

One of the first steps we need to accomplish is to enable NFS under the file services. Navigate to Control Panel > File Services > NFS. Enable the NFS service and set your maximum NFS protocol.

Enable nfs under file services in synology nas
Enable nfs under file services in synology nas

Create and edit your shared folder

Navigate to Control Panel > Shared Folder. Create a new folder, which you can do under the Create menu. Then click Edit.

Editing our kubernetes shared nfs storage folder
Editing our kubernetes shared nfs storage folder

Next, click NFS Permissions. Make sure you have the following defined:

  • Hostname or IP – The IP address or IP range you want to allow to connect
  • Privilege – Read/Write
  • Squash – Map all users to admin
  • Security – sys
  • Enable asynchronous – checked
  • Allow connects from non-privileged ports (ports higher than 1024) – checked
  • Allow users to access mounted subfolders – checked
Setting nfs permissions for kubernetes
Setting nfs permissions for kubernetes

Ok, now we should be configured on the Synology NAS side of things. Next, we will test our connection to the NFS share.

Install NFS client on your Linux test box and Kubernetes hosts

Your Linux test box and Kubernetes hosts may be one and the same. You will need to install the NFS tools on your Kubernetes hosts so they can make the NFS connections needed. I first thought this wasn’t need on the Kubernetes hosts themselves. But, with some testing, this is not the case.

If you don’t install it, you will get an error message when the Kubernetes cluster tries to provision a persistent volume claim using the NFS provisioner.

apt install nfs-common -y
Installing the nfs common tools
Installing the nfs common tools

Testing the connection to the NFS server

We can test using an NFS client root NFS mount. Use the following syntax to test your NFS server/NAS connection. Below is what I used for my environment. Replace with settings from your environment with the NFS client root mountpath.

mount -t nfs /mnt

Now, let’s install the NFS subdir external provisioner.

Installing the NFS subdir external provisioner in your Kubernetes cluster

Now that we have tested the NFS share running on your storage system and can connect to it, let’s install the NFS subdir external provisioner in the Kubernetes cluster. This will install the NFS client provisioner containers from the special container image for the provisioner.

##Add the helm repo
helm repo add nfs-subdir-external-provisioner

##Configure the provisioner for your NFS share
helm install nfs-subdir-external-provisioner nfs-subdir-external-provisioner/nfs-subdir-external-provisioner \
    --set nfs.server=x.x.x.x \
    --set nfs.path=/exported/path

You can also use Kustomize with an NFS client provisioner spec and NFS client provisioner image, deployment metadata, nfs client accessmodes, template, replicas, pod specification, serviceaccount name, etc, or install it manually. Still, it is way more involved than simply using the helm chart.

If you need different role-based access control, you can configure this in rbac.yaml files for authentication, specifying the configuration needed for your app.

Viewing your storage class configuration

After installing the nfs-subdir external provisioner, we can now issue a:

kubectl get sc

Below we see the provisioner_name value listed for the NFS provisioner in the example.

Getting the storage classes configured after installation
Getting the storage classes configured after installation

We see the storage classes listed now as an automatic provisioner. as a note. I did have to change it from the “nfs-01” provisioner that was set as default out of the install to the “nfs-client”. Once I did this, pods were able to provision storage as expected.

If you need to do that, you can use this command:

kubectl patch storageclass nfs-client -p '{"metadata": {"annotations":{"":"true"}}}'

Create a container to use persistent storage

Now that we have the persistent storage configured using the NFS client provisioner, we can create a test container using a deployment.yaml file to test out the automatic provisioning of persistent storage from the persistent storage class.

Below, we are creating an Nginx container and targeting the nfs-client storage class, specifying the PVC size, images, provider, env, labels, etc and storing this in a YAML file.

# pod-with-pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
  name: nginx-pvc
  storageClassName: nfs-client
  accessModes: [ReadWriteOnce]
  resources: { requests: { storage: 5Gi } }
apiVersion: v1
kind: Pod
  name: nginx
    - name: pvc
        claimName: nginx-pvc
    - name: nginx
      image: nginx:latest
        - containerPort: 80
        - name: pvc
          mountPath: /usr/share/nginx/html

Create the file above as pod.yaml or any other name you want with the .yaml extension. Then, we will run the following:

kubectl create -f pod.yaml

Check the persistent volume claims (PVC)

Once the container is created, we can take a look at thepersistentvolumeclaims to see if our Nginx container was able to successfully create the PVC and see if it is in the bound state. You can look at your persistent volumes using the command:

kubectl get pvc

As we can see below, we have a new persistent volume called nginx-pvc and the status is bound.

Persistent volume claim is configured for our nginx pod
Persistent volume claim is configured for our nginx pod

Kubernetes Synology NAS NFS video walkthrough

Frequently Asked Questions

How does NFS Subdir External Provisioner enhance Kubernetes environments?

The NFS Subdir External Provisioner streamlines the process of managing persistent storage in Kubernetes. By automating the provisioning of NFS-based storage, it addresses the dynamic demands of containerized applications, ensuring efficient storage allocation without manual setup.

What are the benefits of using NFS with Kubernetes?

NFS is a tried and true technology that most are running in their environment if they have a NAS storage appliance or other type of storage server configured. With this being the case, you can take advantage of this infrastructure for providing persistent storage for your Kubernetes cluster.

Can NFS Client Provisioner support different access modes for storage?
Yes, the NFS Client Provisioner supports multiple access modes, including ReadWriteMany, ReadWriteOnce, and ReadOnlyMany. This flexibility allows it to cater to diverse storage requirements within Kubernetes, from individual pod storage to shared resources.

What role does Helm Chart play in deploying NFS solutions in Kubernetes?
Helm Charts simplify the deployment of NFS solutions in Kubernetes by bundling all necessary configurations and resources. This aids in the consistent and efficient setup of NFS storage, reducing manual configuration errors and deployment time.

Is backward compatibility maintained with the new NFS Subdir External Provisioner?
Yes, to maintain backward compatibility, especially in deployment configurations, the naming conventions from previous versions, like nfs-client-provisioner, are retained. This ensures a smooth transition for existing Kubernetes setups to the newer provisioner.

How does the NFS Client Root NFS work in a Kubernetes environment?
The NFS Client Root NFS setup involves mounting an NFS share as the root directory for NFS-based persistent volumes. This allows Kubernetes pods to access and store data on a central NFS server, making data sharing and persistence possible across multiple pods.

What do you need to think about with NFS storage and Kubernetes?
Make sure you have the NFS tools installed on your Kubernetes hosts. Also, apply the proper access permissions to your NFS share location for security. With Synology and many others, you can scope down the hosts that can connect to the NFS share by entering allowed IP hosts or ranges.

How does NFS Client Provisioner improve storage management in Kubernetes?
By enabling dynamic provisioning of NFS volumes, the NFS Client Provisioner automates storage allocation, adapting to the changing needs of applications. This minimizes manual intervention and enhances resource utilization efficiency.

Can NFS Subdir External Provisioner be used with pre-provisioned NFS shares?
Yes, the NFS Subdir External Provisioner can work with pre-provisioned NFS shares. It dynamically creates subdirectories in these shares to fulfill Persistent Volume Claims, providing flexibility in managing existing storage resources.

What is the significance of NFS Client Provisioner Spec in Kubernetes?
The NFS Client Provisioner Spec defines the configuration parameters for the NFS Client Provisioner, including details of the NFS server, base path, and mount options. Correct specifications ensure seamless integration and functioning of NFS storage in Kubernetes.

Wrapping up

One of the most important parts of your Kubernetes infrastructure is your storage. Most likely you will want to have persistent storage for at least a few of your pods that depend on having storage for persistent data. Most network environments have a traditional NAS or server with NFS storage configured.

For home lab users, if you are running Synology or TrueNAS in your environment, as we have shown, you can easily set up an NFS share and connect your Kubernetes cluster. Using the NFS subdir external provisioned, you can target your NFS share super easy.

This is a great way to start learning about Kubernetes storage and adding persistent storage to your homelab and even production clusters and take advantage of the data resiliency of your NAS device or NFS solution that is likely backed with some type of redundancy.

Brandon Lee

Brandon Lee is the Senior Writer, Engineer and owner at and has over two decades of experience in Information Technology. Having worked for numerous Fortune 500 companies as well as in various industries, Brandon has extensive experience in various IT segments and is a strong advocate for open source technologies. Brandon holds many industry certifications, loves the outdoors and spending time with family.

Related Articles

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.