Container Service for Kubernetes:Use dynamically provisioned disk volumes for persistent storage

1. Define a template
   You can create a new StorageClass or use a default one as a template for dynamic disk creation. This template defines key parameters, such as disk type, performance level, and reclaim policy.

2. Declare storage requirements in the application

   Define volumeClaimTemplates in the StatefulSet and reference the StorageClass. This declares the specifications for the persistent volume claim (PVC) that the pod will use, such as storage capacity and access mode.

3. Automate volume creation and mounting
   When the StatefulSet creates a pod, the system automatically generates a unique PVC for the pod based on the template. The Container Storage Interface (CSI) component creates a persistent volume (PV) based on the StorageClass rules and binds the PV to the PVC. Finally, the disk is mounted to the pod.

Step 1: Select a StorageClass

ACK provides multiple default StorageClasses. A StorageClass cannot be modified after it is created. If the default configurations do not meet your requirements, you can create a new one. For more information, see Create a StorageClass manually.

Step 2: Create an application and mount a disk

This section uses a StatefulSet as an example to demonstrate how to mount a disk volume.

1. Create a file named statefulset.yaml.

   The following example creates a StatefulSet with two pods. It uses volumeClaimTemplates to automatically create and bind independent persistent storage for each pod.

   apiVersion: apps/v1
   kind: StatefulSet
   metadata:
     name: web
   spec:
     serviceName: "nginx"
     replicas: 2
     selector:
       matchLabels:
         app: nginx
     template:
       metadata:
         labels:
           app: nginx
       spec:
         # We recommend that you configure the following securityContext to optimize mount performance
         securityContext:
           fsGroup: 1000
           fsGroupChangePolicy: "OnRootMismatch"
         containers:
         - name: nginx
           image: anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6
           ports:
           - containerPort: 80
           volumeMounts:
           # Mount the data volume to the /data directory of the container
           # The name must be the same as metadata.name defined in volumeClaimTemplates
           - name: pvc-disk
             mountPath: /data
     # Define the PVC template
     volumeClaimTemplates:
     - metadata:
         name: pvc-disk
       spec:
         # Access mode
         accessModes: [ "ReadWriteOnce" ]
         # Associate the previously created StorageClass
         storageClassName: "alicloud-disk-wait-for-first-consumer"
         resources:
           requests:
             # Requested storage capacity, which is the disk size
             storage: 20Gi

   Important

   Configuring securityContext.fsgroup in a pod causes the kubelet to recursively change file permissions (chmod/chown) when the volume is mounted. If the volume contains many files, this process significantly increases the mount time.

   For clusters that run Kubernetes 1.20 or later, we recommend that you set fsGroupChangePolicy to OnRootMismatch. This setting performs a recursive permission change only on the first mount and only if the permissions of the volume's root directory do not match the required permissions. This optimizes mount performance. If the performance still does not meet your requirements or if you need more granular permission control, we recommend that you use an initContainer to run permission adjustment commands before the main application container starts.

2. Run the following command to create the StatefulSet.

   kubectl create -f statefulset.yaml

3. Run the following command to confirm that the pods are in the Running state.

   kubectl get pod -l app=nginx

4. Run the following command to check the mount path and confirm that the disk is mounted.

   In this example, the pod name is web-1. Replace it with your actual pod name.

   kubectl exec web-1 -- df -h /data

   The following output is expected:

   Filesystem      Size  Used Avail Use% Mounted on
   /dev/vdb         20G   24K   20G   1% /data

What do I do if a PVC is stuck in the Pending state when a pod with a mounted disk is scheduled to a virtual node?

This issue can occur if you use a StorageClass that does not support scheduling to virtual nodes. When you schedule a pod to a virtual node using specific labels or annotations, StorageClasses with the volumeBindingMode: WaitForFirstConsumer mode are not supported.

• Reason:
  The WaitForFirstConsumer mode relies on the kube-scheduler to select a physical node for the pod. This determines the pod's zone, which is then used to create the disk. However, some scheduling mechanisms for virtual nodes do not follow this process. This prevents the Container Storage Interface (CSI) from obtaining the zone information. As a result, the PV cannot be created, and the PVC remains in the Pending state.

• If you encounter this issue, check whether the pod or its namespace contains any of the following configurations:

  • Label:

    • alibabacloud.com/eci: "true": Schedules the pod to an ECI pod.

    • alibabacloud.com/acs: "true": Schedules the pod to an ACS pod.

  • Node specification:

    • The pod directly specifies a node using spec.nodeName. The node name has the prefix virtual-kubelet.

  • Annotation:

    • k8s.aliyun.com/eci-vswitch: Specifies the vSwitch for the ECI pod.

    • k8s.aliyun.com/eci-fail-strategy: "fail-fast": Sets the failure handling policy for the ECI pod to fail-fast.

How do I mount a disk volume for a single pod or a single-replica deployment?

For simple applications that do not require multi-replica scaling or a stable Network ID, manually create a PVC and mount it to a pod or deployment to enable persistent storage.

The process is as follows: Select a StorageClass, create a PVC, and then mount the PVC in the application.

1. Prepare a StorageClass.

2. Create a PVC to request storage resources.

   kubectl

   1. Create a file named disk-pvc.yaml.

      apiVersion: v1
      kind: PersistentVolumeClaim
      metadata:
        name: disk-pvc
      spec:
        # Access mode
        accessModes:
        - ReadWriteOnce
        volumeMode: Filesystem
        resources:
          requests:
            # Requested storage capacity, which is the disk size
            storage: 20Gi
        # Associate with the previously created StorageClass
        storageClassName: alicloud-disk-topology-alltype 

      The following table describes the parameters.

      Parameter	Description
      accessModes	The access mode of the volume. Valid values: ReadWriteOnce, ReadOnlyMany, or ReadWriteMany. The supported values depend on the multiAttach setting in the StorageClass and the volumeMode setting in the PVC. multiAttach specifies whether to enable multi-attach for disks. The default value is false. If multiAttach is false and volumeMode is set to any value, only ReadWriteOnce is supported. If multiAttach is true and volumeMode is Filesystem, only ReadWriteOnce and ReadOnlyMany are supported. If multiAttach is true and volumeMode is Block, all three access modes are supported. Important In this scenario, the access mode is typically ReadWriteOnce (RWO), which means the volume can be mounted by only one pod at a time. Therefore, the number of deployment replicas cannot be greater than 1. If you try to scale out the deployment, the new pods will be stuck in the Pending state because they cannot mount the disk that is already in use.
      volumeMode	The mode of the persistent volume. Valid values: Filesystem (default): The volume is formatted and mounted as a directory. Block: The volume is provided to the pod as an unformatted block device.
      storage	The requested storage capacity. The capacity range varies for different disk types. Make sure that the value of storage complies with the capacity limits of the disk type corresponding to the referenced StorageClass to prevent disk creation failures.
      storageClassName	The StorageClass to bind.

   2. Create a PVC.

      kubectl create -f disk-pvc.yaml

   3. View the PVC.

      kubectl get pvc

      In the output, because the StorageClass uses the WaitForFirstConsumer mode, the PVC is in the Pending state until the first pod that uses it is successfully scheduled.

      NAME       STATUS    VOLUME   CAPACITY   ACCESS MODES   STORAGECLASS                            VOLUMEATTRIBUTESCLASS   AGE
      disk-pvc   Pending                                      alicloud-disk-wait-for-first-consumer   <unset>                 14s

   Console

   1. In the navigation pane on the left of the cluster management page, choose Volumes > Persistent Volume Claims.

   2. On the Persistent Volume Claims page, click Create. Set PVC Type to Cloud Disk and configure the parameters as prompted.

      Parameter	Description
      Allocation Mode	Select Use StorageClass.
      Existing StorageClass	A default or manually created StorageClass.
      Capacity	The requested storage capacity. The capacity range varies for different disk types. Make sure that the value of storage complies with the capacity limits of the disk type corresponding to the referenced StorageClass to prevent disk creation failures.
      Access Mode	Only ReadWriteOnce is supported. This means the volume can be mounted as read-write by a single pod.

      After the PVC is created, you can view it on the Persistent Volume Claims page.

3. Mount the PVC in an application.

   1. Create a file named disk-deployment.yaml.

      Click to view the sample YAML file

      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: single-pod-app
      spec:
        # Make sure the number of replicas is 1
        replicas: 1
        selector:
          matchLabels:
            app: nginx-single
        template:
          metadata:
            labels:
              app: nginx-single
          spec:
            containers:
            - name: nginx
              image: anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6
              ports:
              - containerPort: 80
              # Define the mount point in the container
              volumeMounts:
              - name: my-persistent-storage  # Must match the name defined in volumes below
                mountPath: /data  # Mount to the /data directory in the container
            # Declare and reference the PVC at the pod level
            volumes:
            - name: my-persistent-storage # The volume to be referenced by the container
              persistentVolumeClaim:
                claimName: disk-pvc # Reference the previously created PVC

   2. Run the following command to deploy the deployment.

      kubectl create -f disk-deployment.yaml

4. Verify the mount result.

   1. Verify that the pod is running correctly.

      kubectl get pods -l app=nginx-single

   2. Log on to the pod and check whether the disk is mounted to the /data directory.

      # Get the pod name
      POD_NAME=$(kubectl get pods -l app=nginx-single -o jsonpath='{.items[0].metadata.name}')
      
      # Run the df -h command
      kubectl exec $POD_NAME -- df -h /data

      The following output indicates that the 20 GiB disk is successfully mounted.

      Filesystem      Size  Used Avail Use% Mounted on
      /dev/vdb         20G   24K   20G   1% /data