Container Service for Kubernetes:Using HostPath Volumes

Workflow

After a pod is scheduled to the target node, the kubelet on that node mounts the HostPath volume before the container starts. The kubelet validates and prepares the host path (path) based on the mount type (type) defined in the hostPath field.

• DirectoryOrCreate: If the specified host path does not exist, the kubelet creates an empty directory with permissions set to 0755. The directory owner and group match those of the kubelet.

• Directory: The specified host path must exist and be a directory. Otherwise, the pod fails to start.

• FileOrCreate: If the specified host path does not exist, the kubelet creates an empty file with permissions set to 0644. The file owner and group match those of the kubelet.

• File: The specified host path must exist and be a file. Otherwise, the pod fails to start.

After validation passes, the kubelet bind-mounts the host path into the container. All subsequent read and write operations on the mount point are performed directly on the host file system.

Usage

• Mount HostPath directly in a pod: Define hostPath directly in the pod's volumes. This method is simple but tightly couples storage to the application. Avoid it for production applications that require long-term maintenance or may require storage changes in the future.

• Mount HostPath using a PersistentVolume (PV) and PersistentVolumeClaim (PVC): Define hostPath in a standalone PV. The pod can then request the storage through a PVC. This decouples storage from the application, which lets you manage the underlying storage independently without changing the pod configuration.

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

   This example mounts the node's /data directory to the /test directory 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 host path
         path: /data
         # Specify the mount type
         type: DirectoryOrCreate

2. Deploy the pod.

   kubectl apply -f pod-hostpath-direct.yaml

3. Verify the mount.

   Create a file inside the pod. Then check whether the file exists on the node. This confirms that the mount was successful.

   1. Create a file inside the pod.

      Create a test.txt file in the pod's /test directory, which is the mount point.

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

   2. Obtain the name of the node where the pod is running.

      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.

      For more information, see Log on to a node. Run the ls /data command to check whether the /data directory contains the file that you just created.

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

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

   This example creates a PV that points to the host's /data directory, a PVC that requests that 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 selector to ensure the PVC binds 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. Then check whether the file exists on the node. This confirms that the mount was successful.

   1. Create a file inside the pod.

      Create a test.txt file in the pod's /usr/share/nginx/html directory, which is the mount point.

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

   2. Obtain the name of the node where the pod is running.

      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.

      For more information, see Log on to a node. Run the ls /data command to check whether the /data directory contains the file that you just created.

      If the output includes the test.txt file, the HostPath volume was mounted successfully using the PV and PVC.

Does data in a HostPath volume persist after a pod is deleted and recreated?

This depends on the node to which the new pod is scheduled.

• If the pod is scheduled to the same node: The new pod mounts the same directory on the node and can access all previous data.

• If the pod is scheduled to a new node: The new pod mounts an empty directory on the new node. The data on the original node becomes inaccessible to the new pod.