Use HostPath volumes

Process overview

After a pod is scheduled to a node, the kubelet mounts the HostPath volume before the container starts. It validates and prepares the host path defined in path based on the type in the hostPath configuration.

• DirectoryOrCreate: Checks whether the host path exists. If not, creates an empty directory with 0755 permissions, with ownership and group matching the kubelet.

• Directory: Checks that the host path exists and is a directory. If not, the pod fails to start.

• FileOrCreate: Checks whether the host path exists. If not, creates an empty file with 0644 permissions, with ownership and group matching the kubelet.

• File: Checks that the host path exists and is a file. If not, the pod fails to start.

Once validated, the kubelet bind-mounts the host path into the container. All read and write operations on the mount point go directly to the host node's file system.

Usage methods

• Mount a HostPath volume directly in a pod: Define the hostPath directly in the pod manifest's volumes section. Simple but tightly couples storage to the application. Not recommended for production workloads that require long-term maintenance or may need storage changes.

• Mount a HostPath volume by using a PV and PVC: Define the hostPath in a standalone PV, which a pod requests via a PVC. Decouples storage from the application, letting you manage storage independently without modifying the pod configuration.

1. Create a file named pod-hostpath-direct.yaml.

   Mounts the node's /data directory to /test in the pod.

   apiVersion: v1
   kind: Pod
   metadata:
     name: test-pod
   spec:
     containers:
     - image: anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6
       name: test-container
       volumeMounts:
       - mountPath: /test
         name: test-volume
     volumes:
     - name: test-volume
       hostPath:
         # Specify the path on the host node.
         path: /data
         # Specify the volume type.
         type: DirectoryOrCreate

2. Deploy the pod.

   kubectl apply -f pod-hostpath-direct.yaml

3. Verify the mount.

   Create a file inside the pod and confirm it exists on the node.

   1. Create a file in the pod.

      Create test.txt in the /test directory (mount point) of the pod.

      kubectl exec test-pod -- sh -c 'echo "This file was created from within the Pod." > /test/test.txt'

   2. Get the node name where the pod runs.

      NODE_NAME=$(kubectl get pod test-pod -o jsonpath='{.spec.nodeName}')
      echo "Pod is running on node: $NODE_NAME"

   3. Verify the file on the node.

      Log on to the node and run ls /data to check whether the file exists in the /data directory.

      If the output includes test.txt, the HostPath volume is mounted successfully.

1. Create a file named pv-pvc-hostpath.yaml.

   Creates a PV pointing to the host's /data directory, a PVC that requests the storage, and a pod that uses the PVC.

   # --- PersistentVolume definition ---
   apiVersion: v1
   kind: PersistentVolume
   metadata:
     name: hostpath-pv
     labels:
       type: local
   spec:
     capacity:
       storage: 10Gi
     accessModes:
       - ReadWriteOnce
     hostPath:
       path: "/data"
   ---
   # --- PersistentVolumeClaim definition ---
   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: hostpath-pvc
   spec:
     accessModes:
     - ReadWriteOnce
     resources:
       requests:
         storage: 10Gi
     # Use a selector to bind the PVC to the PV created earlier.
     selector:
       matchLabels:
         type: local
   ---
   # --- Pod definition ---
   apiVersion: v1
   kind: Pod
   metadata:
     name: test-pod-pvc
   spec:
     containers:
       - name: test-container
         image: anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6
         ports:
           - containerPort: 80
         volumeMounts:
           - mountPath: "/usr/share/nginx/html"
             name: storage
     volumes:
       - name: storage
         persistentVolumeClaim:
           # Reference the PVC defined earlier.
           claimName: hostpath-pvc

2. Create the PV, PVC, and pod.

   kubectl apply -f pv-pvc-hostpath.yaml

3. Verify the mount.

   Create a file inside the pod and confirm it exists on the node.

   1. Create a file in the pod.

      Create test.txt in the /usr/share/nginx/html directory (mount point) of the pod.

      kubectl exec test-pod-pvc -- sh -c 'echo "File from PV/PVC Pod." > /usr/share/nginx/html/test.txt'

   2. Get the node name where the pod runs.

      NODE_NAME=$(kubectl get pod test-pod-pvc -o jsonpath='{.spec.nodeName}')
      echo "Pod is running on node: $NODE_NAME"

   3. Verify the file on the node.

      Log on to the node and run ls /data to check whether the file exists in the /data directory.

      If the output includes test.txt, the PV/PVC HostPath volume is mounted successfully.

Does data persist if a pod is recreated?

It depends on which node the pod is scheduled to.

• Scheduled to the same node: The pod mounts the same directory and can access all existing data.

• Scheduled to a different node: The pod mounts an empty directory. Data remains on the original node but is inaccessible.