Mistake on this page? Email us

Provisioning and deleting gateways with the persistent volume plugin

With the edge-pv volume plugin, you can manage a set of directories on a gateway and mount them from containers.

Using this plugin requires creating a StorageClass and a Persistent Volume Claim (PVC) with the volume.kubernetes.io/gateway annotation.

Prerequisites

You need an edge gateway that:

Provisioning the volume

  1. Create a StorageClass:

    $ kubectl create -f edge-pv-storage-class.yaml
    

    edge-pv-storage-class.yaml

    apiVersion: storage.k8s.io/v1
    kind: StorageClass
    metadata:
      name: edge-pv
    provisioner: kubernetes.io/edge-pv
    parameters: {}
    reclaimPolicy: Delete
    allowVolumeExpansion: false
    mountOptions: []
    volumeBindingMode: Immediate
    

    You can list storage classes to verify its creation:

    $ kubectl get storageclass
    NAME       PROVISIONER               AGE
    edge-pv    kubernetes.io/edge-pv     6d1h
    $ 
    
  2. Create a persistent volume claim (PVC) that uses this storage class. This triggers the edge-pv plugin to dynamically provision a directory on the gateway specified in the volume.kubernetes.io/gateway annotation, create a persistent volume object and bind it to this PVC:

    $ kubectl create -f edge-pv-pvc.yaml
    

    edge-pv-pvc.yaml

    apiVersion: v1
    kind: PersistentVolumeClaim
    metadata:
      name: edge-pv-claim
      annotations:
        volume.kubernetes.io/gateway: $GATEWAY_ID
    spec:
      accessModes:
      - ReadWriteOnce
      storageClassName: edge-pv
      resources:
        requests:
          storage: 1Gi
    

    You can list PVCs and persistent volumes to make sure a volume was provisioned and bound. If a problem occurs, such as the gateway's disk being full or the gateway being offline, the PVC remains in the Pending state until the gateway can be reached and a directory created:

    $ kubectl get pvc
    NAME            STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
    edge-pv-claim   Bound    pvc-a08d50a8-84c1-11ea-908c-56f341f212fc   1Gi        RWO            edge-pv        24h
    $ kubectl get pv
    NAME                                       CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS   CLAIM                   STORAGECLASS   REASON   AGE
    pvc-a08d50a8-84c1-11ea-908c-56f341f212fc   1Gi        RWO            Delete           Bound    default/edge-pv-claim   edge-pv                 24h
    $ 
    

    In this example, the edge-pv plugin created a persistent volume bound it to the claim.

  3. Use the PVC in a Pod on the same gateway. Use the volume like you would any other persistent volume:

    $ kubectl create -f edge-pv-pod.yaml
    

    edge-pv-pod.yaml

    apiVersion: v1
    kind: Pod
    metadata:
      name: edge-pv-test
    spec:
      automountServiceAccountToken: false
      nodeName: $GATEWAY_ID
      containers:
      - name: ubuntu
        image: "ubuntu"
        command: ['sleep', '10000000']
        volumeMounts:
        - name: edge-pv-storage
          mountPath: /opt/edge-pv/stuff
      volumes:
      - name: edge-pv-storage
        persistentVolumeClaim:
          claimName: edge-pv-claim
    

Deleting the volume

Deleting the PVC results in the deletion of the corresponding directory from the gateway's disk:

$ kubectl delete pvc edge-pv-claim

If this command hangs and the PVC is stuck in the Terminating state:

  • Delete any Pod using this PVC.
  • Ensure the gateway where the bound PV is provisioned is online and reachable.

You can force Kubernetes to delete a PVC or any other resource stuck in the Terminating state by using the --force --grace-period=0 options with the delete command:

$ kubectl delete --force --grace-period=0 pvc edge-pv-claim

This is not recommended if there is any possibility of bringing the gateway back online to allow for graceful deletion because it bypasses the edge-pv plugin's Deleter, the component ensuring the data is cleaned up from the gateway's disk.

Reference material

Storage class

It is sufficient to create one edge-pv storage class for your account. It can be referenced from multiple persistent volume claims. The storage class describes which volume plugin to use for provisioning a persistent volume to bind to a persistent volume claim. Storage classes also describe what happens when the PVC that is bound to a persistent volume is deleted (see reclaimPolicy). Delete tells Kubernetes that the persistent volume bound to a PVC using this storage class should be deleted when that PVC is deleted.

PersistentVolumeClaim

Use PersistentVolumeClaim (PVC) to specify which gateway the persistent volume bound to this claim should reside on. Please note the volume.kubernetes.io/gateway annotation.

edge-pv vs hostPath

The hostPath plugin lets containers mount and write to directories residing on the same node as the container itself. The edge-pv plugin adds the ability to provision and delete these directories remotely using the Kubernetes PVC and PV API resources. Beyond that, one of hostPath's limitations is you must know the path on the target system you want to mount into your container. The edge-pv plugin creates a directory for each PV provisioned for that gateway in kubelet's root-dir, where it stores all runtime data. When it's time to mount an edge-pv persistent volume, the plugin resolves the host path for that volume's directory automatically based on the persistent volume name. The edge-pv plugin also provides protections, so a Pod is not allowed to mount a volume unless it is provisioned for the same gateway.