Tutorial: Learn How To Mount A Local Directory Into A Pod In minikube!

The use case for this guide is as follows: A Kubernetes (k8s, see also the Kubernetes website) engineer needs to mount a local directory into a pod in minikube since pod storage is ephemeral and will be deleted when the pod is deleted.

Note that Kubernetes administrators can also use the kubectl command to copy files from a pod to the local environment as well and for simple debugging this option tends to work well.

Kubernetes Mount Host Directory TOC

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 — a skill that comes in handy frequently when developing microservices in Kubernetes.

This article was updated on June 17, 2025.

Prerequisites

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.

Learn how to create pods inside minikube!

This tutorial explains how to create two pods in k8s using kubectl -- perfect for sharpening your CKAD practice exam skills.
Create pods in k8s now!

Do you need to restart a pod in k8s?

There’s no built-in kubectl command to restart a pod in k8s, however there are alternative methods covered in this tutorial.
Restart a Pod in k8s Now!

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.

Shell output showing the result of running "minikube ssh" and then "df -hl" including a pointer to the "/Users" directory -- this demonstrates how to mount a local directory into a pod in minikube.
The "/Users" directory has been mounted in minikube.

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

In the first step we add a hostPath path entry to the pod configuration file on lines 19 and 20 under the minimounted volume and point the path to a directory in the user’s 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:

Terminal output where we get command line access to the pod and then cat the hello.txt file and we can see that the contents of this file.
Example bash shell output for a container running in minikube with the /etc/minimounted/ directory which now contains the hello.txt file.

Step Two: Start minikube using the hyperv-virtual-switch option

The second 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.

Command line output when starting the minikube cluster with the hyperkit driver using the command "minikube start --hyperv-virtual-switch "My Virtual Switch" --v=4".
minikube start cluster using the hyperkit driver.

Step Three: Apply the configuration.

 In the script below we apply the configuration file.

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

We can see the output when the kubectl apply command is executed below.

The kubectl apply output when mounting a local directory to a pod in minikube.
Output when mounting a local directory to a pod.

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.

Terminal / Oh My Zsh output for Solution #1: Mount a subdirectory in a pod in Minikube within user home. We 1.) restart minikube with no mount-related args, then 2.) we create the 'myns' namespace and run the nginx pod, finally 3.) we get terminal access to the pod and can see that the /etc/minimounted directory exists and contains the hello.txt file.
We mount a subdirectory within the pod's user home and display the contents of the hello.txt file.

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.

CTO Consulting Services

If you're looking to hire a consultant Chief Technology Officer then find a time that works for you on my Google Calendar and we can discuss your Interim CTO or Fractional CTO consulting requirements in more detail.
Schedule An Appointment!

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 when we start minikube.

In this step we 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.

Terminal shell output demonstrating that the /etc/minimounted/ directory is empty after applying the Kubernetes minikube configuration changes.
Command-line output of a container running in k8s minikube with the empty /etc/minimounted/ directory.

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

In order to get this working, 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/"

Example output for the successful execution of this command appears in the following image.

The user executes the minikube start command with parameters for mounting a directory in the pod outside of the user's home directory as follows: minikube start --hyperv-virtual-switch "My Virtual Switch" --v=4 --mount --mount-string="/etc/minimount/:/minimounted/" and minikube starts successfully and with zero errors and/or warnings.
User successfully executes the minikube start command with parameters for mounting a directory in the pod.

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 pod

In order to confirm that this is working correctly, we need to check that the /etc/minimounted directory exists in the pod and that it 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

When we execute these commands we should end up with something that looks like what appears in the following image.

Terminal output where we get command line access to the pod and then cat the hello.txt file and we can see that the contents of this file.
Example bash shell output for a container running in minikube with the /etc/minimounted/ directory which now contains the hello.txt file.

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 how to do this here.

Unfortunately 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.

Step One: Restart minikube

In the first step we need to restart minikube — we can use the command below for this.

				
					minikube stop && minikube start

Restarting minikube should result in output that looks similar to the following image.

Terminal shell where the user has run "minikube stop && minikube start" with output indicating that the restart has been performed successfully.
Restart minikube using the 'minikube stop && minikube start' commands.

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

Next we confirm that the /etc/minikube/ directory is empty — this is expected as we need to apply a configuration file before the directory will have any files in it, however it is important to note that the directory does exist.

The following image demonstrates how we can confirm that the directory exists and is empty.

User obtains terminal access to the pod and check that the /etc/minimount directory exists and is empty.
User obtains terminal access to the pod and check that the /etc/minimount directory exists and is empty.

The red arrow points to the kubectl command that is used to obtain shell access in the running pod — this command is available below.

				
					kubectl exec nginx-minimounted -n myns -it -- /bin/sh

The blue arrow is used to verify that the /etc/minimounted directory is empty.

				
					ls -la

The green arrow exits the command line shell running in the pod.

				
					exit

Step Three: Mount the directory.

In the third step we mount the directory using the minikube mount command.

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

The full minikube mount command used in the image above is included here:

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

An example of a successful execution of the minikube mount command appears below.

User successfully links the /.../k8s-study/minimounted directory on the host machine to the /minimounted/ directory within the Minikube VM.
Link the user's /.../k8s-study/minimounted directory on the host machine to the /minimounted/ directory within the Minikube VM.

In the next step we apply the nginx-minimounted.yaml pod configuration file.

Step Four: Apply the pod configuration.

In the fourth step we apply the nginx-minimounted.yaml pod configuration file , which contains hostPath and volumeMounts settings — the file appears below followed by the command.

				
					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 the nginx-minimounted.yaml pod configuration file has been saved on your local machine apply the configuration as follows:

				
					kubectl apply -f ./nginx-minimounted.yaml

An example of the successful application of this configuration file is shown below.

User successfully applies the pod configuration file using the following command: 'kubectl apply -f ./nginx-minimounted.yaml'.
Apply the pod configuration file.

Step Five: Confirm that the /etc/minimounted directory contains the hello.txt file.

In the fifth step we check if the /etc/minimounted directory in the pod now contains the expected files, and it does!

User checks the pod's /etc/minimounted directory and can see that the hello.txt file exists.
User checks the pod's /etc/minimounted directory and can see that the hello.txt file exists.

The minikube mount exercise full output.

For convenience, I’ve include the entire script here (and on GitHub).

				
					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 nginx-minimounted -n myns -it -- /bin/sh
cat /etc/minimounted/hello.txt

A full copy of the expected output when the script is executed appears below.

Terminal output where 1.) minikube is restarted 2.) we delete a pod 3.) we mount the directory 4.) we run the pod 5.) we verify that we can now see the contents of the hello.txt file in the pod.
Mounting a directory in minikube without requiring a restart.

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

Tutorial Conclusion

In conclusion, effectively mounting a local directory into a pod running in Minikube enhances data persistence and facilitates seamless development workflows within your Kubernetes environments.

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

Questions and comments are welcomed.

Hat Tip

I’d like to express my thanks to the following colleagues who assisted with the review and/or editing of this article:

Tutorial Frequently Asked Questions (FAQ)

What is a volume mount in Kubernetes?

A volume mount in Kubernetes is a way to map a volume (a defined storage unit in a Kubernetes cluster) to a directory in a container.

A volume mount provides the container with data access and persistent storage of data throughout the lifecycle of the container.

What is minikube used for?

Minikube is used to run Kubernetes locally — this provides the software engineer with the ability to test and develop applications in a Kubernetes environment without the need for a full Kubernetes cluster.

What is the minikube mount command?

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.

Tutorial References

  1. Mount local directory into pod in minikube
  2. MountVolume.SetUp failed for volume “mongo” : hostPath type check failed: /mongo/data is not a directory
  3. hostpath : MountVolume.SetUp failed for volume “test-volume” : hostPath type check failed: /data is not a directory
  4. Invalid Error: .container.volumes: hostPath type check failed: “not a directory”
  5. Kubernetes Volumes
  6. Mounting filesystems in minikube
  7. Configure a Pod to Use a Volume for Storage
  8. Configure a Pod to Use a PersistentVolume for Storage
  9. Intro to Windows support in Kubernetes
  10. juliohm1978 / kubernetes-cifs-volumedriver
  11. kubernetes / examples (staging volumes NFS)
  12. Kubernetes DefaultMountDir (constants in Golang for Darwin, Linux, and Windows) — the link is no longer available.
  13. GoDoc package homedir
  14. hostpath type check failed is not a directory
  15. kubernetes volume mount
  16. kubernetes hostpath
  17. kubernetes hostpath mount
  18. minikube volume
  19. Docker failed to mount local volume mount error.
  20. Learn how to use kubectl to get the cluster name in our tutorial which explains how to acquire this information via the command line.
  21. Learn how to mount a host directory into the virtual machine (VM) on k8s.io
author avatar
ThosPFuller
I am a software engineer based in Northern Virginia (USA) and this website focuses on content engineering, web development, Technical SEO, Search Engine Optimization (SEO).
See Full Bio
social network icon
Tags: , , , , , ,

Leave a Reply