Persistent storage using hostPath

A hostPath volume in an OKD cluster mounts a file or directory from the host node’s filesystem into your pod. Most pods will not need a hostPath volume, but it does offer a quick option for testing should an application require it.

The cluster administrator must configure pods to run as privileged. This grants access to pods in the same node.

Overview

OKD supports hostPath mounting for development and testing on a single-node cluster.

In a production cluster, you would not use hostPath. Instead, a cluster administrator would provision a network resource, such as a GCE Persistent Disk volume, an NFS share, or an Amazon EBS volume. Network resources support the use of storage classes to set up dynamic provisioning.

A hostPath volume must be provisioned statically.

Do not mount to the container root, /, or any path that is the same in the host and the container. This can corrupt your host system if the container is sufficiently privileged. It is safe to mount the host by using /host. The following example shows the / directory from the host being mounted into the container at /host.

  1. apiVersion: v1
  2. kind: Pod
  3. metadata:
  4. name: test-host-mount
  5. spec:
  6. containers:
  7. - image: registry.access.redhat.com/ubi9/ubi
  8. name: test-container
  9. command: [‘sh’, ‘-c’, sleep 3600’]
  10. volumeMounts:
  11. - mountPath: /host
  12. name: host-slash
  13. volumes:
  14. - name: host-slash
  15. hostPath:
  16. path: /
  17. type: ‘’

Statically provisioning hostPath volumes

A pod that uses a hostPath volume must be referenced by manual (static) provisioning.

Procedure

  1. Define the persistent volume (PV). Create a file, pv.yaml, with the PersistentVolume object definition:

    1. apiVersion: v1
    2. kind: PersistentVolume
    3. metadata:
    4. name: task-pv-volume (1)
    5. labels:
    6. type: local
    7. spec:
    8. storageClassName: manual (2)
    9. capacity:
    10. storage: 5Gi
    11. accessModes:
    12. - ReadWriteOnce (3)
    13. persistentVolumeReclaimPolicy: Retain
    14. hostPath:
    15. path: "/mnt/data" (4)
    1The name of the volume. This name is how it is identified by persistent volume claims or pods.
    2Used to bind persistent volume claim requests to this persistent volume.
    3The volume can be mounted as read-write by a single node.
    4The configuration file specifies that the volume is at /mnt/data on the cluster’s node. Do not mount to the container root, /, or any path that is the same in the host and the container. This can corrupt your host system. It is safe to mount the host by using /host.
  2. Create the PV from the file:

    1. $ oc create -f pv.yaml
  3. Define the persistent volume claim (PVC). Create a file, pvc.yaml, with the PersistentVolumeClaim object definition:

    1. apiVersion: v1
    2. kind: PersistentVolumeClaim
    3. metadata:
    4. name: task-pvc-volume
    5. spec:
    6. accessModes:
    7. - ReadWriteOnce
    8. resources:
    9. requests:
    10. storage: 1Gi
    11. storageClassName: manual
  4. Create the PVC from the file:

    1. $ oc create -f pvc.yaml

Mounting the hostPath share in a privileged pod

After the persistent volume claim has been created, it can be used inside by an application. The following example demonstrates mounting this share inside of a pod.

Prerequisites

  • A persistent volume claim exists that is mapped to the underlying hostPath share.

Procedure

  • Create a privileged pod that mounts the existing persistent volume claim:

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4. name: pod-name (1)
    5. spec:
    6. containers:
    7. ...
    8. securityContext:
    9. privileged: true (2)
    10. volumeMounts:
    11. - mountPath: /data (3)
    12. name: hostpath-privileged
    13. ...
    14. securityContext: {}
    15. volumes:
    16. - name: hostpath-privileged
    17. persistentVolumeClaim:
    18. claimName: task-pvc-volume (4)
    1The name of the pod.
    2The pod must run as privileged to access the node’s storage.
    3The path to mount the host path share inside the privileged pod. Do not mount to the container root, /, or any path that is the same in the host and the container. This can corrupt your host system if the container is sufficiently privileged, such as the host /dev/pts files. It is safe to mount the host by using /host.
    4The name of the PersistentVolumeClaim object that has been previously created.