Tutorial: How To Mount A Local Directory Into A Pod In minikube (2022)

The background to this problem is as follows: A software developer needs to mount a local directory into a pod in minikube. The reason a software developer would need this is that pod storage is ephemeral and will be deleted when the pod is deleted. If we want the storage to survive a pod deletion or to be shared between pods, then we can mount a directory from the local file system. This could be a requirement, for example, when you have a database running in the pod but the storage is located on the local filesystem.

In this article, we’ll cover several examples that demonstrate how to mount a local directory in a pod running in minikube.

We rely on minikube (v1.15.1) with kubectl (1.19.4) on Ubuntu (20.04.1 LTS) as well as on Mac OSX (10.13.6 High Sierra).

The k command, which appears below, is defined as follows:

				
					alias k='kubectl'

In the next section we’ll take a look at several use cases regarding why a software developer would want to mount a local directory in a pod in Kubernetes and/or minikube and following that we’ll take a look at a few solutions.

Use Cases for mounting a local directory in a pod in Kubernetes

Mounting a local directory into a pod in Kubernetes can be useful for several reasons and I’ve included five use cases below. At a high level these benefits include data sharing and accelerating the development and testing of software.

Configuration Injection

You can mount a local directory containing configuration files or environment variables into a pod. This allows you to dynamically adjust the behavior of your application without modifying the container image. As you update the configuration on the host machine, the changes are immediately reflected in the pod thereby facilitating easy configuration management.

Data Sharing and Backup

Mounting a shared local directory allows you to share data between containers within the same pod. This enables seamless communication and data exchange, such as sharing log files or database backups between containers. Additionally, you can use local directories as temporary storage for data backups and then mount the local directories into pods for further processing.

Persistent Data Storage

You can mount a local directory into a pod when one or more applications require persistent storage. This approach can be particularly useful during development and testing, and allows you to use your local machine’s file system as a data storage solution. Local storage is not recommended for production scenarios due to its limitations and lack of scalability however it is perfectly suitable for development and testing purposes.

Debugging and Troubleshooting

When debugging an application within a pod, mounting a local directory with debugging tools, scripts, or diagnostic utilities can help you quickly investigate issues. Mounting a local directory allows the developer access to debugging tools and logs directly from the local machine and streamlines the troubleshooting process.

Development and Testing

Mounting a local directory can accelerate the iteration process when it comes to developing and testing software. Instead of building and pushing container images for every code change, you can mount the directory containing the source code into the pod and enable real-time testing and observation of the changes as development progresses.

Keep in mind that while mounting a local directory can be helpful for specific use cases, it’s essential to consider the security and portability implications as it pertains to production software. Using ConfigMaps, Configuration Secrets, or network-attached storage solutions such as Persistent Volumes (see also Configure a Pod to Use a PersistentVolume for Storage) and Persistent Volume Claims (PVCs)) might be more appropriate for production environments, where data needs to be managed securely and scaled effectively.

In the next section we’ll take a look at what the minikube mount command does and then we’ll take a look at three solutions that we can use to mount a host directory in a pod in minikube.

What is minikube mount?

The minikube mount command allows the developer to mount a local directory on the host machine into a running Minikube cluster, thereby making it accessible to containers running in the cluster. In the following examples we do not use minikube mount directly — instead we apply a configuration yaml file which has the mount specification details included.

See also the page on mounting filesystems regarding how to mount a host directory into the virtual machine (VM) on k8s.io for more details regarding how minikube mount is used.

Solution #1: Mount a subdirectory within user's home into a pod in minikube (easiest)

In the first solution, which is also the easiest solution in this article, we mount a subdirectory within the user’s home directory into a pod in minikube. This solution was inspired by [1] (Akshay Sood, specifically) and facilitates the same result as Solution #2 however without the requirement to pass the –mount and –mount-string args. The pod configuration file looks very close to the one used in Solution #2 as well — direct your attention to lines 14 (volumeMounts) and 17 (volumes).

This works because minikube mounts the /Users directory by default on Mac OSX, which is what we’re using for this specific solution.

Refer to the homedir package documentation as well as the for more information regarding the directory paths per specific supported operating systems (Apple OSX, Linux, and Microsoft Windows) [12 & 13]. I also have a simple script, which is written in Go, in GitHub, which displays the value of the user’s home directory.

In the image below we can see which directory has been mounted in minikube by invoking the df command with the h option, for displaying human-readable output, and the l option, which reveals information about locally-mounted filesystems.

Step One: Modify the hostPath in the pod configuration below to point to the user home directory.

Here’s the pod configuration:

				
					apiVersion: v1
kind: Pod
metadata:
  creationTimestamp: null
  labels:
    run: nginx-minimounted
  name: nginx-minimounted
  namespace: myns
spec:
  containers:
  - image: nginx
    name: nginx-minimounted
    resources: {}
    volumeMounts:
      - mountPath: /etc/minimounted
        name: minimounted
  volumes:
    - name: minimounted
      hostPath:
        path: /Users/thospfuller/k8s-study/minimounted
  dnsPolicy: ClusterFirst
  restartPolicy: Never
status: {}

In this example, we start minikube absent any of the mount-related args. When the pod is created the /etc/minimounted/ directory will exist and it will be correctly mapped to the local directory. We can see the output of this example in the following image:

Step Two: Start minikube

The first step requires us to start minikube using the hyperv-virtual-switch option as follows:

				
					minikube start --hyperv-virtual-switch "My Virtual Switch" --v=4

In this example the –hyperv-virtual-switch parameter is described on k8s.io as:

Name of the virtual switch the minikube VM should use. Defaults to first found

and we’re using “My Virtual Switch” as the name. The –v option sets the log level verbosity.

Step Three: Apply the configuration.

In the script below we apply the configuration file.

				
					kubectl apply -f ./nginx-hp-minimounted.yaml

Step Four (optional): Test that the path is available in the pod in minikube

We can test that the path is available by getting command line access to the pod in the myns namespace and checking that the path exists as follows:

				
					kubectl exec nginx-minimounted -n myns -it -- /bin/sh
ls -la /etc/minimounted

Below I’ve included the complete script for running and testing this solution below.

				
					minikube start --hyperv-virtual-switch "My Virtual Switch" --v=4
kubectl apply -f ./nginx-hp-minimounted.yaml
kubectl exec nginx-minimounted -n myns -it -- /bin/sh
ls -la /etc/minimounted
exit

If everything worked as we expect it to we should see something that looks like what appears below.

And that’s it for this example. In the next section we’ll see how to mount a directory outside of user home into a pod in minikube

Solution #2: Mount a directory outside of user home into a pod in minikube

Note that as a precondition to the instructions below you should create a /minimounted/ directory and include a hello.txt file with “…world!” as the contents.

The second solution should be fairly straightforward however it’s not exactly given the pod configuration in the example here. Solution #2 attempts to mount the /etc/minimounted/ directory and since the /etc directory is not mounted by default, we need to add command line args when minikube is started to instruct minikube to mount a local directory to a directory in minikube and then when the pod is created it will mount that directory to a directory in the pod itself.

If we just follow an example for mounting a local directory in a pod in Kubernetes, when we have shell access to the pod and check the path, the directory will exist however it will be empty.

Reference [1] (Shahriar, specifically) explains the solution pretty closely however a fully working solution is not provided and we’ll deliver that now.

Step One: Modify the hostPath path in the pod configuration file.

The following pod configuration file should work but, as we’ll see in a moment, it doesn’t and that’s because in order to mount local directory that is outside of the user home directory to pod we need to include extra arguments.

In this step we can modify the hostPath path such that it points to a directory somewhere on the machine we’re using however it should not be (for this example), inside the user’s home directory.

				
					apiVersion: v1
kind: Pod
metadata:
  creationTimestamp: null
  labels:
    run: nginx-minimounted
  name: nginx-minimounted
  namespace: myns
spec:
  volumes:
  - name: minimounted
    hostPath:
      path: /minimounted/
      type: DirectoryOrCreate
  containers:
  - image: nginx
    name: nginx-minimounted
    resources: {}
    volumeMounts:
      - mountPath: /etc/minimounted
        name: minimounted
  dnsPolicy: ClusterFirst
  restartPolicy: Never
status: {}

Here’s an example of what the minikube start script might look like — we need to change this in order to get this working.

minikube start --hyperv-virtual-switch "My Virtual Switch" --v=4

The following image demonstrates the problem inside the pod — note the /etc/minimounted/ directory is empty whereas we’re expecting the hello.txt file to be there.

Step Two: Add the mount and mount-string arguments to the minikube start command.

In order to make this work, we need to start minikube with the following mount and mount-string options set:

				
					minikube start --hyperv-virtual-switch "My Virtual Switch" --v=4 --mount --mount-string="/etc/minimount/:/minimounted/"

We have /etc/minimount/ mounted as /minimounted/ in minikube and when we run the nginx-minimounted pod the /minimounted/ directory will be mounted as /etc/minimounted/ in the pod; we can see the directory contents in the image below.

Step Three: Check the /etc/minimounted directory in the minikube pod

In order to confirm that this is working correctly, we need to check that the /etc/minimounted directory exists and also contains the hello.txt file that we expect to be there — we can do this using the script below.

				
					kubectl exec nginx-minimounted -n myns -it -- /bin/sh
ls -la /etc/nginx-minimounted
cat /etc/nginx-minimounted/hello.txt

In this example we can see that the hello.txt file does exist and that it contains the text “world!”, which is what we expect to be in it.

Let’s take a look at Solution #3.

Solution #3: Mount a directory other than user home, without restart, into a pod in minikube

It is possible to mount the directory without restarting minikube and we’ll demonstrate this here. Unfortunately, however, we’ll need to recreate the pod otherwise the pod’s /etc/minimounted/ directory will still be empty. If you know how to achieve this same result without restarting the pod, please include the details in the comments.

Regarding the following image: first, we restart minikube and can see that the /etc/minikube/ directory is empty.

Finally, we can see the contents of the /etc/minimounted/hello.txt file.

Step One: Restart minikube

In step one we simply stop and start minikube. We can use the command below for this step.

				
					minikube stop && minikube start

Step Two: Confirm that the /etc/minikube/ directory is empty

Next we confirm that the /etc/minikube/ directory is empty — this is demonstrated by the fifth blue arrow in the image below.

Step Three: Mount the directory.

Next, we mount the directory. Keep in mind that this command must be executed as a background process or we’ll need to open another terminal.

				
					minikube mount /Users/thospfuller/k8s-study/minimounted:/minimounted/ &

In the next step we apply the pod configuration.

Step Four: Apply the pod configuration

In step four we apply the pod configuration using the example below.

The configuration yaml file appears below and following that is the command that needs to be executed.

				
					apiVersion: v1
kind: Pod
metadata:
  creationTimestamp: null
  labels:
    run: nginx-minimounted
  name: nginx-minimounted
  namespace: myns
spec:
  volumes:
  - name: minimounted
    hostPath:
      path: /minimounted/
      type: DirectoryOrCreate
  containers:
  - image: nginx
    name: nginx-minimounted
    resources: {}
    volumeMounts:
      - mountPath: /etc/minimounted
        name: minimounted
  dnsPolicy: ClusterFirst
  restartPolicy: Never
status: {}

Once this file has been saved on your local machine apply the configuration as follows:

				
					kubectl apply -f ./nginx-minimounted.yaml

A copy of the expected output appears below.

For convenience, I’ve include the entire script below.

				
					minikube stop && minikube start
kubectl apply -f ./nginx-minimounted.yaml
kubectl exec nginx-minimounted -n myns -it -- /bin/sh
ls -la /etc/minimounted
exit
kubectl delete pods nginx-minimounted -n myns
minikube mount /Users/thospfuller/k8s-study/minimounted:/minimounted/ & kubectl apply -f ./nginx-minimounted.yaml 
kubectl exec ngin -minimounted -n myns -it -- /bin/sh
cat /etc/minimounted/hello.txt

And that’s it for the third example, and for this article.

Mount a Local Directory Into a Pod in minikube: Article Conclusion

If you liked this article you may also like the following articles, also written by yours truly:

Addressing problems such as the one described in this article can be difficult when working in isolation. One strategy which can help make this easier is pair programming, which is part of the Agile Software Development methodology.

Please add comments below if you find an error with anything written here or have a question about this document.