Oracle Cloud Infrastructure Documentation

Creating a Persistent Volume Claim

Container storage via a container's root file system is ephemeral, and can disappear upon container deletion and creation. To provide a durable location to prevent data from being lost, you can create and use persistent volumes to store data outside of containers.

A persistent volume offers persistent storage that enables your data to remain intact, regardless of whether the containers to which the storage is connected are terminated.

A persistent volume claim (PVC) is a request for storage, which is met by binding the PVC to a persistent volume (PV). A PVC provides an abstraction layer to the underlying storage. For example, an administrator could create a number of static persistent volumes that can later be bound to one or more persistent volume claims. If none of the static persistent volumes match the user's PVC request, the cluster may attempt to dynamically create a new PV that matches the PVC request.

With Oracle Cloud Infrastructure as the underlying IaaS provider, you can provision persistent volume claims by attaching volumes from the Oracle Cloud Infrastructure Block Volume service. The volumes are connected to clusters created by Container Engine for Kubernetes using FlexVolume and CSI (Container Storage Interface) volume plugins deployed on the clusters.

The minimum amount of persistent storage that a PVC can request is 50 gigabytes. If the request is for less than 50 gigabytes, the request is rounded up to 50 gigabytes.

For more information about persistent volumes, persistent volume claims, and volume plugins, see the Kubernetes documentation.

Provisioning Persistent Volume Claims on the Block Volume Service

The Oracle Cloud Infrastructure Block Volume service (the Block Volume service) provides persistent, durable, and high-performance block storage for your data. You can use the CSI volume plugin or the FlexVolume volume plugin to connect clusters to volumes from the Block Volume service. Using the CSI volume plugin has several advantages:
  • In future, new functionality will only be added to the CSI volume plugin, not to the FlexVolume volume plugin (although Kubernetes developers will continue to maintain the FlexVolume volume plugin).
  • The CSI volume plugin does not require access to underlying operating system and root file system dependencies.

The StorageClass specified for a PVC controls which volume plugin to use to connect to Block Volume service volumes. If you don't explicitly specify a value for storageClassName in the yaml file that defines the PVC, the cluster's default StorageClass is used. In clusters created by Container Engine for Kubernetes, the oci StorageClass is initially set up as the default. The oci StorageClass is used by the FlexVolume volume plugin.

In the case of the CSI volume plugin, the CSI topology feature ensures that worker nodes and volumes are located in the same availability domain. In the case of the FlexVolume volume plugin, you can use the matchLabels element to select the availability domain in which a persistent volume claim is provisioned. Note that you do not use the matchLabels element with the CSI volume plugin.

Note

In the FlexVolume examples in this topic, the PVCs request storage in availability domains in the Ashburn region using the failure-domain.beta.kubernetes.io/zone label. For more information about using this label (and the shortened versions of availability domain names to specify), see failure-domain.beta.kubernetes.io/zone.

Specifying the Volume plugin used by a Persistent Volume Claim

To explicitly specify the volume plugin to use to connect to the Block Volume service when provisioning a persistent volume claim, specify a value for storageClassName in the yaml file that defines the PVC:

  • to use the CSI volume plugin, specify storageClassName: "oci-bv"
  • to use the FlexVolume volume plugin, specify storageClassName: "oci"

Example 1: Dynamically Creating a Persistent Volume on the Block Volume Service for Use by the CSI Volume Plugin

In this example, the cluster administrator has not created any suitable PVs that match the PVC request. As a result, a block volume is dynamically provisioned using the CSI plugin specified by the oci-bv StorageClass's definition (provisioner: blockvolume.csi.oraclecloud.com).

You define a PVC in a file called csi-bvs-pvc.yaml. For example:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: mynginxclaim
spec:
  storageClassName: "oci-bv"
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 50Gi

Enter the following command to create the PVC from the csi-bvs-pvc.yaml file:

kubectl create -f  csi-bvs-pvc.yaml

The output from the above command confirms the creation of the PVC:

persistentvolumeclaim "mynginxclaim" created

Verify that the PVC has been created by running kubectl get pvc:

kubectl get pvc

The output from the above command shows the current status of the PVC:

		
NAME               STATUS   VOLUME   CAPACITY   ACCESSMODES   STORAGECLASS   AGE
mynginxclaim       Pending                                    oci-bv         4m

The PVC has a status of Pending because the oci-bv StorageClass's definition includes volumeBindingMode: WaitForFirstConsumer.

You can use this PVC when creating other objects, such as pods. For example, you could create a new pod from the following pod definition, which instructs the system to use the mynginxclaim PVC as the nginx volume, which is mounted by the pod at /data.

apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  containers:
    - name: nginx
      image: nginx:latest
      ports:
        - name: http
          containerPort: 80
      volumeMounts:
        - name: data
          mountPath: /usr/share/nginx/html
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: mynginxclaim

Having created the new pod, you can verify that the PVC has been bound to a new persistent volume by entering:

kubectl get pvc

The output from the above command confirms that the PVC has been bound:

			
NAME               STATUS    VOLUME                               CAPACITY   ACCESSMODES   STORAGECLASS   AGE
mynginxclaim       Bound     ocid1.volume.oc1.iad.<unique_ID>     50Gi       RWO           oci-bv         4m

You can verify that the pod is using the new persistent volume claim by entering:

kubectl describe pod nginx

Example 2: Dynamically Creating a Persistent Volume on the Block Volume Service for Use by the FlexVolume Volume Plugin

In this example, the cluster administrator has not created any suitable PVs that match the PVC request. As a result, a block volume is dynamically provisioned using the FlexVolume volume plugin specified by the oci StorageClass's definition (provisioner: oracle.com/oci).

You define a PVC in a file called flex-bvs-pvc.yaml. For example:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: mynginxclaim
spec:
  storageClassName: "oci"
  selector:
    matchLabels:
      failure-domain.beta.kubernetes.io/zone: "US-ASHBURN-AD-1"
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 50Gi

Note that the flex-bvs-pvc.yaml file includes the matchLabels element, which is only applicable in the case of the FlexVolume volume plugin.

Enter the following command to create the PVC from the flex-bvs-pvc.yaml file:

kubectl create -f  flex-bvs-pvc.yaml

The output from the above command confirms the creation of the PVC:

persistentvolumeclaim "mynginxclaim" created

Verify that the PVC has been created and bound to a new persistent volume by entering:

kubectl get pvc

The output from the above command shows the current status of the PVC:

			
NAME               STATUS    VOLUME                               CAPACITY   ACCESSMODES   STORAGECLASS   AGE
mynginxclaim       Bound     ocid1.volume.oc1.iad.<unique_ID>     50Gi       RWO           oci            4m

The PVC already has a status of Bound because the oci StorageClass's definition includes volumeBindingMode: Immediate.

You can use this PVC when creating other objects, such as pods. For example, the following pod definition instructs the system to use the mynginxclaim PVC as the nginx volume, which is mounted by the pod at /data.

apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  containers:
    - name: nginx
      image: nginx:latest
      ports:
        - name: http
          containerPort: 80
      volumeMounts:
        - name: data
          mountPath: /usr/share/nginx/html
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: mynginxclaim

Having created the new pod, you can verify that it is running and using the new persistent volume claim by entering:

kubectl describe pod nginx

Example 3: Creating a Persistent Volume from a Backup on the Block Volume Service for Use by the FlexVolume Volume Plugin

In this example, the cluster administrator has created a block volume backup for you to use when provisioning a new persistent volume claim. The block volume backup comes with data ready for use by other objects such as pods.

You define a PVC in a file called flex-pvcfrombackup.yaml file. You use the volume.beta.kubernetes.io/oci-volume-source annotation element to specify the source of the block volume to use when provisioning a new persistent volume claim using the FlexVolume volume plugin. You can specify the OCID of either a block volume or a block volume backup as the value of the annotation. In this example, you specify the OCID of the block volume backup created by the cluster administrator. For example:

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: myvolume
  annotations:
    volume.beta.kubernetes.io/oci-volume-source: ocid1.volumebackup.oc1.iad.abuw...
spec:
  selector:
    matchLabels:
      failure-domain.beta.kubernetes.io/zone: US-ASHBURN-AD-1
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 50Gi

Note that the flex-pvcfrombackup.yaml file includes the matchLabels element, which is only applicable in the case of the FlexVolume volume plugin.

Enter the following command to create the PVC from the flex-pvcfrombackup.yaml file:

kubectl create -f flex-pvcfrombackup.yaml

The output from the above command confirms the creation of the PVC:

persistentvolumeclaim "myvolume" created

Verify that the PVC has been created and bound to a new persistent volume created from the volume backup by entering:

kubectl get pvc

The output from the above command shows the current status of the PVC:

			
NAME           STATUS    VOLUME                               CAPACITY   ACCESSMODES   STORAGECLASS   AGE
myvolume       Bound     ocid1.volume.oc1.iad.<unique_ID>     50Gi       RWO           oci            4m

You can use the new persistent volume created from the volume backup when defining other objects, such as pods. For example, the following pod definition instructs the system to use the myvolume PVC as the nginx volume, which is mounted by the pod at /data.

apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  containers:
    - name: nginx
      image: nginx:latest
      ports:
        - name: http
          containerPort: 80
      volumeMounts:
        - name: data
          mountPath: /usr/share/nginx/html
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: myvolume

Having created the new pod, you can verify that it is running and using the new persistent volume claim by entering:

kubectl describe pod nginx