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 matchLabels:failure-domain.beta.kubernetes.io/zone.

When you specify a value for the failure-domain.beta.kubernetes.io/zone Kubernetes label, you must use the correct shortened version of an availability domain name in an Oracle Cloud Infrastructure region. In most cases, the shortened versions of availability domain names are in the format <region-identifier>-1-AD-<availability-domain-number>. For example UK-LONDON-1-AD-1, UK-LONDON-1-AD-2, UK-LONDON-1-AD-3, AP-MELBOURNE-1-AD-1, ME-JEDDAH-1-AD-1.

However, the shortened versions of availability domain names in the Ashburn and Phoenix regions are exceptions, as shown below:

  • For the Phoenix region, shortened versions of availability domain names are in the format PHX-AD-<availability-domain-number>. For example, PHX-AD-1, PHX-AD-2, PHX-AD-3.
  • For the Ashburn region, shortened versions of availability domain names are in the format US-ASHBURN-AD-<availability-domain-number>. For example, US-ASHBURN-AD-1, US-ASHBURN-AD-2, US-ASHBURN-AD-3.

For a full list of the shortened versions of availability domain names, see Availability by Region.

For more information about Kubernetes labels, see the Kubernetes documentation.

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

persistentvolumeclaim "mynginxclaim" created

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

$ kubectl get 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 running kubectl get pvc:

$ kubectl get pvc
			
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 running 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

persistentvolumeclaim "mynginxclaim" created

Verify that the PVC has been created and bound to a new persistent volume by running kubectl get pvc:

$ kubectl get 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 running 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 volume backup for you to use when provisioning a new persistent volume claim. The 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. The annotation element volume.beta.kubernetes.io/oci-volume-source refers to the volume backup by its OCID. 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
	  
persistentvolumeclaim "myvolume" created

Verify that the PVC has been created and bound to a new persistent volume created from the volume backup by running kubectl get pvc:

$ kubectl get 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 running kubectl describe pod nginx