Use dynamic volumes and cloud disks

1. Define a template
   Create or use a default StorageClass as a template to dynamically create cloud disks. The StorageClass specifies key parameters, such as the disk type, performance, and reclaim policy.
   
   

2. Declare storage requirements in the application

   In the StatefulSet, define volumeClaimTemplates and reference the StorageClass to specify the storage capacity and access mode for the PVCs.

3. Automatically create and mount storage volumes
   When the StatefulSet creates a Pod, the system automatically generates a unique PVC for the Pod based on the template. The CSI component then creates a PV based on the StorageClass, binds the PV to the PVC, and mounts the corresponding cloud disk to the Pod.
   
   

Step 1: Choose a StorageClass

ACK provides several default StorageClasses. Since a StorageClass cannot be modified after creation, you can manually create a StorageClass if the default configurations do not meet your requirements.

Step 2: Create an application with a cloud disk

This section uses a StatefulSet as an example to show how to mount a Cloud 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 an independent persistent volume 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 configuring 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 in the container.
           # The name must match 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 with the StorageClass created earlier.
         storageClassName: "alicloud-disk-wait-for-first-consumer"
         resources:
           requests:
             # Requested storage capacity, which is the size of the Cloud Disk.
             storage: 20Gi

   Important

   When you configure securityContext.fsgroup, the kubelet recursively changes file permissions (chmod/chown) when mounting a volume. This can significantly increase mount time for volumes with many files.

   For clusters of version 1.20 or later, we recommend setting fsGroupChangePolicy to OnRootMismatch. This optimizes mount performance by only performing the recursive permission change when the volume is first mounted and the root directory permissions do not match. If performance remains an issue or you require more granular permission control, use an initContainer to manage permissions before the application container starts.

2. Create the StatefulSet.

   kubectl create -f statefulset.yaml

3. Verify that the Pods are running.

   kubectl get pod -l app=nginx

4. Verify that the Cloud Disk is mounted.

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

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

   Expected output:

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

PVC stuck in Pending state when scheduled to a virtual node

This issue can occur if you use a StorageClass that does not support scheduling to virtual nodes. When a pod is scheduled to a virtual node using specific labels or annotations, you cannot use a StorageClass configured with volumeBindingMode: WaitForFirstConsumer.

• Reason:
  The WaitForFirstConsumer mode relies on the kube-scheduler to select a physical node for a Pod. This selection determines the availability zone, and a cloud disk is then created in that availability zone. However, the scheduling mechanism for virtual nodes does not follow this process. This prevents the CSI from obtaining the availability zone information, which in turn prevents the PV from being created, leaving the PVC in the Pending state.
  
  

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

  • Label:

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

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

  • Node pinning:

    • Setting spec.nodeName to a node name with the virtual-kubelet prefix pins the pod to that node.

  • Annotation:

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

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

Mount a cloud disk for a single pod or single-replica deployment

For simple applications that do not require multi-replica scaling or stable network identifiers, you can manually create a PersistentVolumeClaim and mount it to a pod or a Deployment for persistent storage.

The workflow is as follows: Choose a StorageClass -> Create a PersistentVolumeClaim -> Mount the PersistentVolumeClaim in your application.

1. Prepare a StorageClass.

2. Create a PersistentVolumeClaim 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 size of the cloud disk
            storage: 20Gi
        # Associate with the StorageClass created earlier
        storageClassName: alicloud-disk-topology-alltype 

      The following table describes the parameters.

      Parameter	Description
      accessModes	The access modes of the volume. Valid values are ReadWriteOnce, ReadOnlyMany, and ReadWriteMany. The supported access modes depend on the multiAttach setting in the StorageClass and the volumeMode setting in the PersistentVolumeClaim. multiAttach specifies whether to enable cloud disk multi-attach. The default value is false, which means the feature is disabled. When multiAttach is false and volumeMode is set to any value, the only supported access mode is ReadWriteOnce. When multiAttach is true and volumeMode is Filesystem, the supported access modes are ReadWriteOnce and ReadOnlyMany. When multiAttach is set to true and volumeMode is set to Block, all three access modes are supported. Important In this scenario, the access mode is typically ReadWriteOnce (RWO), which means that it can be mounted by only one Pod at a time. Therefore, the number of Deployment replicas cannot be greater than 1. If you attempt to scale out, new Pods will remain in the Pending state because they cannot mount the cloud disk that is already in use.
      volumeMode	The mode of the volume. Valid values: Filesystem (default): The volume is formatted and mounted as a directory. Block: The volume is provided to the pod as a raw, unformatted block device.
      storage	The requested storage capacity. Different cloud disk types have different capacity ranges. Ensure that the value of storage is within the capacity limits of the cloud disk type that corresponds to the referenced StorageClass to prevent cloud disk creation failure.
      storageClassName	The name of the StorageClass to use for this claim.

   2. Create the PersistentVolumeClaim.

      kubectl create -f disk-pvc.yaml

   3. Check the PersistentVolumeClaim.

      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 left navigation pane of the cluster management page, choose Volumes > Persistent Volume Claims.

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

      Parameter	Description
      Allocation Mode	Select Use StorageClass.
      Existing Storage Class	Select a default or manually created StorageClass.
      Capacity	The requested storage capacity. Different cloud disk types have different capacity ranges. Ensure that the value of storage is within the capacity limits of the cloud disk type that corresponds to the referenced StorageClass to prevent cloud disk creation failure.
      Access Mode	This scenario supports only ReadWriteOnce, which means a single pod can mount the volume with read-write access.

      After creating the PersistentVolumeClaim, you can view it on the Persistent Volume Claims page.

3. Mount the PersistentVolumeClaim in your application.

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

      Expand to view example YAML

      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: single-pod-app
      spec:
        # Ensure the replica count 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 # Volume to be referenced by the container
              persistentVolumeClaim:
                claimName: disk-pvc # Reference the PVC created earlier

   2. Deploy the Deployment.

      kubectl create -f disk-deployment.yaml

4. Verify the mount result.

   1. Confirm that the pod is running.

      kubectl get pods -l app=nginx-single

   2. Connect to the pod and verify that the cloud 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 on the mount point
      kubectl exec $POD_NAME -- df -h /data

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

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