Addon: Hostpath Storage

The hostpath storage MicroK8s add-on can be used to easily provision PersistentVolumes backed by a host directory. It is ideal for local development, but for all uses it is important to be aware:

• PersistentVolumeClaims created by the hostpath storage provisioner are bound to the local node, so it is impossible to move them to a different node.
• A hostpath volume can grow beyond the capacity set in the volume claim manifest.

Enable

microk8s enable hostpath-storage

Verify

Create an example pod with a PVC, using the microk8s-hostpath storage class. Note that the microk8s-hostpath storage class is marked as default, so you do not have to specify a storageClassName for the PVC definition:

microk8s kubectl apply -f - <<EOF
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: test-pvc
spec:
  accessModes: [ReadWriteOnce]
  resources: { requests: { storage: 1Gi } }
---
apiVersion: v1
kind: Pod
metadata:
  name: test-nginx
spec:
  volumes:
    - name: pvc
      persistentVolumeClaim:
        claimName: test-pvc
  containers:
    - name: nginx
      image: nginx
      ports:
        - containerPort: 80
      volumeMounts:
        - name: pvc
          mountPath: /usr/share/nginx/html
EOF

Then use microk8s kubectl get pod,pvc to verify that the volume and the container were successfully created:

NAME             READY   STATUS    RESTARTS   AGE
pod/test-nginx   1/1     Running   0          32s

NAME                             STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS        AGE
persistentvolumeclaim/test-pvc   Bound    pvc-c48dbcc1-ca7e-482d-954f-b9e80119e438   1Gi        RWO            microk8s-hostpath   52s

You can also use microk8s kubectl describe pv to see more details about the volume that was provisioned. Two fields of note are Node Affinity (which mentions the node that the provisioned volume is bound to) and Source (which mentions the local directory where the volume data is stored).

Name:              pvc-c48dbcc1-ca7e-482d-954f-b9e80119e438
Labels:            <none>
Annotations:       hostPathProvisionerIdentity: u2
                   pv.kubernetes.io/provisioned-by: microk8s.io/hostpath
Finalizers:        [kubernetes.io/pv-protection]
StorageClass:      microk8s-hostpath
Status:            Bound
Claim:             default/test-pvc
Reclaim Policy:    Delete
Access Modes:      RWO
VolumeMode:        Filesystem
Capacity:          1Gi
Node Affinity:
  Required Terms:
    Term 0:        kubernetes.io/hostname in [u2]
Message:
Source:
    Type:          HostPath (bare host directory volume)
    Path:          /var/snap/microk8s/common/default-storage/default-test-pvc-pvc-c48dbcc1-ca7e-482d-954f-b9e80119e438
    HostPathType:  DirectoryOrCreate

Customize directory used for PersistentVolume

NOTE: This feature is available starting from MicroK8s 1.25

By default, the hostpath provisioner will store all volume data under /var/snap/microk8s/common/default-storage. It is possible that a cluster administrator might want to change this path, or support different paths (e.g. so that they specify a path backed by SSD storage).

This is possible via the use of custom storage classes, by specifying the pvDir parameter. For example, to create an ssd-hostpath storage class that stores data under /mnt/ssd-disk:

1. Create the storage class definition like so:

   ---
   # ssd-hostpath-sc.yaml
   kind: StorageClass
   apiVersion: storage.k8s.io/v1
   metadata:
     name: ssd-hostpath
   provisioner: microk8s.io/hostpath
   reclaimPolicy: Delete
   parameters:
     pvDir: /mnt/ssd-disk
   volumeBindingMode: WaitForFirstConsumer
   

2. Apply the storage class on the cluster:

   microk8s kubectl apply -f ssd-hostpath-sc.yaml
   

3. Ensure that the storage class was created successfully with microk8s kubectl get storageclass ssd-hostpath:

   NAME           PROVISIONER            RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
   ssd-hostpath   microk8s.io/hostpath   Delete          WaitForFirstConsumer   false                  52s
   

4. Create an example PVC using the ssd-hostpath storageclass:

   microk8s kubectl apply -f - <<EOF
   ---
   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: test-pvc-ssd
   spec:
     storageClassName: ssd-hostpath
     accessModes: [ReadWriteOnce]
     resources: { requests: { storage: 1Gi } }
   ---
   apiVersion: v1
   kind: Pod
   metadata:
     name: test-nginx-ssd
   spec:
     volumes:
       - name: pvc
         persistentVolumeClaim:
           claimName: test-pvc-ssd
     containers:
       - name: nginx
         image: nginx
         ports:
           - containerPort: 80
         volumeMounts:
           - name: pvc
             mountPath: /usr/share/nginx/html
   EOF
   

5. Ensure that the volume data is stored under /mnt/ssd-disk with microk8s kubectl describe pv. The output should look like this:

   Name:              pvc-e8991951-ed72-4c62-978e-7f01621a0828
   Labels:            <none>
   Annotations:       hostPathProvisionerIdentity: u2
                      pv.kubernetes.io/provisioned-by: microk8s.io/hostpath
   Finalizers:        [kubernetes.io/pv-protection]
   StorageClass:      ssd-hostpath
   Status:            Bound
   Claim:             default/test-pvc-ssd
   Reclaim Policy:    Delete
   Access Modes:      RWO
   VolumeMode:        Filesystem
   Capacity:          1Gi
   Node Affinity:
   Required Terms:
       Term 0:        kubernetes.io/hostname in [u2]
   Message:
   Source:
       Type:          HostPath (bare host directory volume)
       Path:          /mnt/ssd-disk/default-test-pvc-ssd-pvc-e8991951-ed72-4c62-978e-7f01621a0828
       HostPathType:  DirectoryOrCreate
   Events:            <none>