An illustration of PersistentVolume is shown in the following graph. First, the administrator provisions the specification of a PersistentVolume. Then the consumer requests for storage with PersistentVolumeClaim. Finally, the Pod mounts the volume with the reference of PersistentVolumeClaim:

Here is an example using NFS. The administrator needs to provision and allocate PersistentVolume first:

# example of PV with NFS
$ cat 2-6-7_pv.yaml
  apiVersion: "v1"
  kind: "PersistentVolume"
  metadata:
    name: "pvnfs01"
  spec:
    capacity:
      storage: "3Gi"
    accessModes:
      - "ReadWriteOnce"
    nfs:
      path: "/"
      server: "<your nfs server>"
    persistentVolumeReclaimPolicy: "Recycle"

# create the pv
$ kubectl create -f 2-6-7_pv.yaml
persistentvolume "pvnfs01" created

We can see that there are three parameters here: capacity, accessModes, and persistentVolumeReclaimPolicy. capacity is the size of this PersistentVolume. Now, accessModes is based on the capability of the storage provider and can be set to a specific mode during provision. For example, NFS supports multiple readers and writers simultaneously—then we can specify the accessModes as one of ReadWriteOnce, ReadOnlyMany, or ReadWriteMany. Now, persistentVolumeReclaimPolicy is used to define the behavior when PersistentVolume is released. The currently supported policy is retain and recycle for nfs and hostPath. You have to clean the volume by yourself in retain mode; on the other hand, Kubernetes will scrub the volume in recycle mode.

PV is a resource like a node. We could use kubectl get pv to see current provisioned PVs:

# list current PVs
$ kubectl get pv
NAME LABELS CAPACITY ACCESSMODES STATUS CLAIM REASON AGE
pvnfs01 <none> 3Gi RWO Bound default/pvclaim01 37m

Next, we will need to bind PersistentVolume with PersistentVolumeClaim in order to mount it as volume into the pod:

# example of PersistentVolumeClaim
$ cat claim.yaml
apiVersion: "v1"
kind: "PersistentVolumeClaim"
metadata:
  name: "pvclaim01"
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi

# create the claim
$ kubectl create -f claim.yaml
persistentvolumeclaim "pvclaim01" created

# list the PersistentVolumeClaim (pvc)
$ kubectl get pvc
NAME LABELS STATUS VOLUME CAPACITY ACCESSMODES AGE
pvclaim01 <none> Bound pvnfs01 3Gi RWO 59m

The constraints of accessModes and storage can be set in PersistentVolumeClaim. If the claim is bound successfully, its status will turn to Bound; on the other hand, if the status is Unbound, it means there is no PV currently matching the requests.

Then we are able to mount the PV as volume with the reference of PersistentVolumeClaim:

# example of mounting into Pod
$ cat nginx.yaml
apiVersion: v1
kind: Pod
metadata:
  name: nginx
  labels:
    project: pilot
    environment: staging
    tier: frontend
spec:
  containers:
    -
      image: nginx
      imagePullPolicy: IfNotPresent
      name: nginx
      volumeMounts:
      - name: pv
        mountPath: "/usr/share/nginx/html"
      ports:
      - containerPort: 80
  volumes:
    - name: pv
      persistentVolumeClaim:
        claimName: "pvclaim01"

# create the pod
$ kubectl create -f nginx.yaml
pod "nginx" created

It will be similar syntax to other volume types. Just add the claimName of persistentVolumeClaim in the volume definition. We are all set! Let's check the details to see whether we mounted it successfully:

# check the details of a pod
$ kubectl describe pod nginx
...
Volumes:
  pv:
    Type: PersistentVolumeClaim (a reference to a PersistentVolumeClaim in the same namespace)
    ClaimName: pvclaim01
    ReadOnly: false
...

We can see we have a volume mounted in the Pod nginx with the type pv pvclaim01. Use docker inspect to see how it is mounted:

"Mounts": [
        {
            "Source": "/var/lib/kubelet/pods/<id>/volumes/kubernetes.io~nfs/pvnfs01",
            "Destination": "/usr/share/nginx/html",
            "Mode": "",
            "RW": true
        },
                ...
    ]

Kubernetes mounts /var/lib/kubelet/pods/<id>/volumes/kubernetes.io~nfs/< persistentvolume name> into the destination in the Pod.