Use a statically provisioned cloud disk volume in Alibaba Cloud ACK-Container Service for Kubernetes(ACK)-阿里云帮助中心

By manually creating a PV and PVC, you can mount a cloud disk to a Pod as a statically provisioned volume. This method provides persistent storage, ideal for workloads that require high disk I/O performance and low latency without data sharing.

Disks are ideal for the following use cases:

Applications that require high disk I/O but not shared data access, such as MySQL or Redis.
High-speed log writing.
Persistent storage for data that must persist beyond the pod lifecycle.

Workflow

Create a PV
Register an existing cloud disk in your cluster by specifying its ID, capacity, access mode, and zone affinity. This ensures that the Pod is scheduled to the correct node.
Create a PVC
Your application requests storage resources through a PVC, which then binds to a compatible PV.
Mount the PVC in your application
Mount the bound PVC into your application Pod, making it available as a persistent directory within the container.

Prerequisites

CSI component requirements: The csi-plugin and csi-provisioner components must be installed.
The CSI components are installed by default. Check the Add-ons page to ensure they are still installed. We recommend upgrading the CSI components to the latest version.
The cloud disk must be in the Available state and meet the following requirements:
- Availability zone limitations: Except for ESSD zone-redundant cloud disks, other cloud disk types can only be attached to pods in the same availability zone.
- Instance type family limitations: Some cloud disk types can only be attached to specific instance type families.
Virtual node limitations: To use a cloud disk on a virtual node, your cluster and kube-scheduler must meet the following version requirements.
Version requirements
Cluster version
Kube-scheduler version
1.28 or later
6.9.3 or later
1.26
6.8.7
1.24
6.4.7
1.22
6.4.5
Lingjun node limitations: To use cloud disks on Lingjun nodes, the following requirements must be met.
Details
- CSI components: v1.34.3 or later.
- Cloud disk tag:
  1. Go to ECS console - Block Storage - Disks.
  2. When you create a cloud disk, add the createdByProduct:eflo tag. You can only add this tag during disk creation.
    Example:
    If the OperationDenied.HpnZoneMismatch error occurs during mounting, see What do I do if a Pod event reports the "OperationDenied.HpnZoneMismatch" error when I mount a cloud disk to a Lingjun node?.
  After creation, use this cloud disk to manually create a PV and bind it with a PVC. This cloud disk can only be scheduled to Lingjun nodes.

Step 1: Create a PV

Create a PV to declare an existing cloud disk as an available storage resource in the cluster.

kubectl

Create a file named disk-pv.yaml with the following content.

Obtain the disk ID, disk size, zone ID, and disk category, and replace the variables in the YAML file with the actual values.

apiVersion: v1
kind: PersistentVolume
metadata:
  # The ID of your existing cloud disk, such as d-uf628m33r5rsbi******
  name: "<YOUR-DISK-ID>"
  annotations:
    # Recommended. Ensures the Pod is scheduled to a node that supports this disk type.
    # <YOUR-DISK-CATEGORY> is the category of your existing cloud disk. Supported values include cloud_essd_entry, cloud_auto, cloud_essd, cloud_ssd, cloud_efficiency, and cloud_regional_disk_auto.
    csi.alibabacloud.com/volume-topology: '{"nodeSelectorTerms":[{"matchExpressions":[{"key":"node.csi.alibabacloud.com/disktype.<YOUR-DISK-CATEGORY>","operator":"In","values":["available"]}]}]}'
spec:
  capacity:
    # The size of your existing cloud disk, such as 20Gi.
    storage: "<YOUR-DISK-SIZE>"
  claimRef:
    apiVersion: v1
    kind: PersistentVolumeClaim
    namespace: default
    name: disk-pvc
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  csi:
    driver: diskplugin.csi.alibabacloud.com
    # The ID of your existing cloud disk, such as d-uf628m33r5rsbi******
    volumeHandle: "<YOUR-DISK-ID>"
  nodeAffinity:
    required:
      nodeSelectorTerms:
      - matchExpressions:
        - key: topology.diskplugin.csi.alibabacloud.com/zone
          operator: In
          values:
          # The zone where the cloud disk is located, such as cn-shanghai-f.
          - "<YOUR-DISK-ZONE-ID>"
  storageClassName: alicloud-disk-topology-alltype
  volumeMode: Filesystem

The following table describes the key parameters.

Parameter	Description
`csi.alibabacloud.com/volume-topology`	This annotation sets node affinity for the cloud disk, ensuring that Pods using this disk are scheduled to nodes that support the corresponding disk type. This prevents mount failures due to node incompatibility. To ensure accurate scheduling, we recommend that you specify the disk category. The supported types are as follows: ESSD Entry disk: `cloud_essd_entry` ESSD AutoPL disk: `cloud_auto` ESSD disk: `cloud_essd` Standard SSD: `cloud_ssd` Ultra disk: `cloud_efficiency` Zone-redundant disk: `cloud_regional_disk_auto` (requires adjustments to the nodeAffinity parameter)
`claimRef`	Specifies the PVC that can bind to this PV. To allow any PVC to bind to this PV, remove this parameter.
`accessModes`	The access mode. The supported mode depends on whether the multi-attach feature for cloud disks is enabled. Multi-attach disabled: Only `ReadWriteOnce` (RWO) is supported. The cloud disk can be mounted to a single node in read/write mode. Multi-attach enabled: As a standard file system (formatted): Supports `ReadWriteOnce` (RWO) and `ReadOnlyMany` (ROX). To prevent data corruption from concurrent writes to file systems like ext4 across multiple nodes, the `ReadWriteMany` (RWX) mode is not supported. As a raw block device (unformatted): Supports `ReadWriteOnce` (RWO), `ReadOnlyMany` (ROX), and `ReadWriteMany` (RWX).
`persistentVolumeReclaimPolicy`	The reclaim policy for the PV, which determines what happens to the PV and the underlying cloud disk when the bound PVC is deleted. `Delete`: When the PVC is deleted, both the PV and the cloud disk are deleted. Use this setting with caution. To prevent accidental data loss, you can create an automatic snapshot policy to back up the cloud disk before deletion. `Retain`: When the PVC is deleted, the PV and cloud disk are not deleted. You must release them manually.
`driver`	Set to `diskplugin.csi.alibabacloud.com` when using Alibaba Cloud disks.
`nodeAffinity`	Node affinity settings. Except for ESSD zone-redundant disks, other cloud disk types can only be attached to Pods within the same zone. This configuration ensures that Pods are scheduled to ECS nodes in the same zone as the cloud disk. For zone-redundant disks, change the configuration to the following to allow the disk to be mounted in any zone within the region. In this configuration, `<YOUR-DISK-REGION-ID>` is the region where the cloud disk is located, such as `cn-shanghai`. `nodeAffinity: required: nodeSelectorTerms: - matchExpressions: - key: topology.kubernetes.io/region operator: In values: - "<YOUR-DISK-REGION-ID>"`
`storageClassName`	This setting has no effect on statically provisioned volumes, and you do not need to create a corresponding StorageClass. However, you must ensure that the value of this setting is the same in both the PV and PVC.

Create the PV.
```
kubectl create -f disk-pv.yaml
```

Check the status of the PV and make sure it is Available.

kubectl get pv

Expected output:

NAME                     CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS      CLAIM              STORAGECLASS                             VOLUMEATTRIBUTESCLASS   REASON   AGE
d-uf628m33r5rsbi******   20Gi       RWO            Retain           Available   default/disk-pvc   alicloud-disk-topology-alltype           <unset>                          1m36s

Console

On the ACK Clusters page, click the name of your cluster. In the left navigation pane, click Volumes > Persistent Volumes.

On the Persistent Volumes page, click Create, set PV Type to Cloud Disk, and configure the PV parameters as prompted.

Parameter	Description
Access Mode	Only ReadWriteOnce is supported.
Disk ID:	Click Select Disk and select an unmounted cloud disk in the same region and zone as the node.
File System Type:	Select the file system type for storing data on the cloud disk. Supported File System Type: include ext4, ext3, xfs, and vfat.

Step 2: Create a PVC

Create a PVC to bind to the PV you created in the previous step.

kubectl

Create a file named disk-pvc.yaml with the following content.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: disk-pvc
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      # The requested storage capacity, which must match the PV capacity.
      storage: "<YOUR-DISK-SIZE>"
  # Must match the storageClassName defined in the PV.
  storageClassName: alicloud-disk-topology-alltype
  # Specify the PV to bind to.
  volumeName: "<YOUR-DISK-ID>"

The following table describes the key parameters.

Parameter	Description
`accessModes`	The access mode. Must be consistent with the PV configuration.
`storage`	The storage capacity allocated to the Pod. Must be consistent with the PV capacity.
`storageClassName`	This setting has no effect on statically provisioned volumes, and you do not need to create a corresponding StorageClass. However, you must ensure that the value of this setting is the same in both the PV and PVC.
`volumeName`	Specifies the PV to bind to. To allow the PVC to bind to any matching PV, remove this parameter.

Create the PVC.
```
kubectl create -f disk-pvc.yaml
```

Check the status of the PVC and make sure it is Bound.

kubectl get pvc

Expected output, which indicates that the PVC is bound to the cloud disk PV:

NAME                       STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS                     VOLUMEATTRIBUTESCLASS   AGE
disk-pvc                   Bound    d-bp1ff1mn65jk8s******                     20Gi       RWO            alicloud-disk-topology-alltype   <unset>                 6s

Console

In the left navigation pane of the cluster management page, choose Storage > PVCs.

On the Persistent Volume Claims page, click Create, set PVC Type to Disk, and create a PVC as prompted.

Parameter	Description
Allocation Mode	Select Existing Volumes.
Existing Volumes	Select the PV you created earlier.
Capacity	The storage capacity allocated to the Pod, which cannot exceed the capacity of the cloud disk.

Step 3: Create an application and mount the cloud disk

Create a workload and use the cloud disk by mounting the PVC.

Important

A Cloud Disk provides non-shared storage and, unless multi-attach is enabled, can be mounted to only one Pod at a time. Sharing a PVC in a multi-replica Deployment can prevent new Pods from starting if the Cloud Disk is already in use by another Pod.

If you still need to use a Cloud Disk with a Deployment, consider using a Cloud Disk as an ephemeral volume. To enable multi-attach, see Use NVMe-based Cloud Disks with multi-attach and reservation.

kubectl

Create a file named disk-test.yaml with the following content.
The following example creates a StatefulSet with one replica. The Pod requests storage resources through a PVC named disk-pvc and mounts the volume to the /data path.
```
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: disk-test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6
        ports:
        - containerPort: 80
        volumeMounts:
        - name: pvc-disk
          mountPath: /data
      volumes:
        - name: pvc-disk
          persistentVolumeClaim:
            claimName: disk-pvc
```
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.
- When a Pod is rebuilt, it remounts the original cloud disk. If other constraints prevent the Pod from being scheduled to the original zone, it will remain in the Pending state because it cannot mount the cloud disk.
Create the StatefulSet and mount the cloud disk.
```
kubectl create -f disk-test.yaml
```

Check the status of the Pod and make sure it is Running.

kubectl get pod -l app=nginx

Expected output:

NAME          READY   STATUS    RESTARTS   AGE
disk-test-0   1/1     Running   0          14s

Check the mount path to confirm that the cloud disk is mounted.

kubectl exec disk-test-0 -- df -h /data

Expected output:

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

Console

In the left navigation pane of the cluster management page, choose Workload > StatefulSets.
On the StatefulSets page, click Create from Image.

On the StatefulSets page, click Create from Image, and follow the prompts on the page to configure the StatefulSet parameters.

The following table describes the main configuration items. For detailed configuration instructions, see Create a StatefulSet.

Configuration page	Parameter	Description
Basic Information	Replicas:	Configure the number of replicas for the StatefulSet.
Container	Image Name	Enter the address of the image used to deploy the application, such as `anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6`.
	Required Resources	Set the required vCPU, memory, and ephemeral storage resources. In this example, CPU is set to 0.25 Core, and memory is set to 512 MiB.
	Volume	Click Add PVC, then configure the parameters. Mount Source: Select the PVC you created earlier. Container Path: Enter the path in the container to which the cloud disk is mounted, such as /data.

Check the deployment status of the application.
1. On the StatefulSets page, click the name of the application.
2. On the Pods tab, make sure the Pod is in the Running state.

Verify data persistence

Follow the "write data > delete the Pod > check data" process to verify that data stored on the cloud disk persists after the Pod is rebuilt.

Write test data to the Pod.
1. Check the mount path to view the data on the cloud disk.
```
kubectl exec disk-test-0 -- ls /data
```
  Expected output:
```
lost+found
```
2. Write test data to the Pod.
  Take the Pod disk-test-0 as an example. Create a test file in the /data directory, which is the mount path of the cloud disk.
```
kubectl exec disk-test-0 -- touch /data/test
```
Simulate a Pod failure by deleting the Pod.
```
kubectl delete pod disk-test-0
```
Run the kubectl get pod -l app=nginx command again. A Pod with the same name is automatically created.
Verify the data in the new Pod.
Check the /data directory in the new Pod disk-test-0 again.
```
kubectl exec disk-test-0 -- ls /data
```
In the expected output, the previously created test file still exists, indicating that the data persists even after the Pod is deleted and rebuilt.
```
lost+found  
test
```

Production considerations

High availability
- Pod scheduling policy
  Correctly configure nodeAffinity and csi.alibabacloud.com/volume-topology in the PV to ensure that the Pod can be successfully scheduled and the cloud disk can be remounted after the Pod is rebuilt.
- Cloud disk selection
  Evaluate factors such as performance, billing, availability zones, and instance type families to ensure your pods are scheduled to compatible nodes.
  When you select a cloud disk type, note that SSD cloud disks and Ultra cloud disks are being phased out. We recommend using ESSD PL0 cloud disks or ESSD Entry cloud disks to replace Ultra cloud disks, and ESSD AutoPL cloud disks to replace SSD cloud disks.
- Cross-AZ disaster recovery
  - Application-level disaster recovery: For critical workloads such as databases, deploy application instances across multiple availability zones and use the application's native data synchronization mechanism for high availability.
  - Storage-level disaster recovery: Choose a cloud disk type that supports multi-AZ disaster recovery. This feature writes data synchronously to different availability zones within the same region, enabling cross-AZ failover. For more information, see Use ESSD Co-located Redundant Disks.
Data security
- Routine backups: Use an automatic snapshot policy to create snapshots for your cloud disks for data backup and recovery.
Performance and cost optimization
- Parallel attach
  To accelerate pod startup, use parallel attach for cloud disks.
- Storage monitoring and alerts
  Configure alerts based on container storage monitoring to promptly detect storage volume anomalies or performance bottlenecks.

Clean up resources

To avoid unexpected charges and ensure data security, follow this process to release unused resources.

Delete the workload
- Action: Delete all applications that use the relevant PVC, such as Deployments and StatefulSets. This action stops the running Pods and unmounts the volumes.
  Example command: kubectl delete deployment <your-deployment-name>
Delete the PVC
- Action: Delete the PVC associated with the application. After deletion, what happens to the bound PV depends on its persistentVolumeReclaimPolicy.
- Reclaim policy details:
  - Retain: After the PVC is deleted, the status of its bound PV changes to Released, but the PV object and the backend cloud disk are retained. If you confirm that the cloud disk and all its data are no longer needed, see Release a cloud disk to delete it. This action is irreversible, so proceed with caution.
  - Delete: After the PVC is deleted, both the PV object and the backend cloud disk are deleted. The data on the cloud disk will be permanently lost and cannot be recovered. Use this policy with caution.
    To prevent accidental data loss, you can create an automatic snapshot policy to back up the cloud disk before deletion.
- Example command: kubectl delete pvc <your-pvc-name>
Delete the PV object: This action only removes the resource definition from the cluster and does not delete the backend cloud disk.
- Action: Manually delete the PV that is in the Released state.
- Example command: kubectl delete pv <your-pv-name>

Cluster version	Kube-scheduler version
1.28 or later	6.9.3 or later
1.26	6.8.7
1.24	6.4.7
1.22	6.4.5

Workflow

Prerequisites

Step 1: Create a PV

kubectl

Console

Step 2: Create a PVC

kubectl

Console

Step 3: Create an application and mount the cloud disk

kubectl

Console

Verify data persistence

Production considerations

Clean up resources

Related documents