Provision Disk Volumes via CLI for StatefulSet Workloads - Container Service for Kubernetes

When a pod requires persistent storage, managing disk creation and attachment manually adds operational overhead. Dynamic provisioning removes that overhead: when you submit a persistent volume claim (PVC), ACK automatically provisions an Alibaba Cloud disk and binds it to the PVC as a persistent volume (PV). To use dynamic provisioning, create a StorageClass that specifies the disk type and zone placement, then reference it in your PVC.

Prerequisites

Before you begin, ensure that you have:

A running ACK cluster with kubectl configured
Sufficient permissions to create StorageClass, PVC, and Pod resources

How it works

Create a StorageClass that specifies the disk type and provisioning parameters.
Submit a PVC that references the StorageClass.
ACK provisions a disk and binds it to the PVC as a PV.
Mount the PV in a pod by referencing the PVC name.

Choose a provisioning mode

ACK supports two provisioning modes. Choose based on your cluster topology and scheduling requirements.

Mode	When to use	Zone selection
zoneId mode	Single-zone clusters, or when you want to pin volumes to specific zones	Specified by `zoneId`; uses round-robin if multiple zones are listed
WaitForFirstConsumer mode	Multi-zone clusters where pod scheduling should drive volume placement	Zone of the node where the pod is scheduled

If you omit both zoneId and volumeBindingMode: WaitForFirstConsumer, the disk is created in the zone where the Disk-Controller component is deployed.

Create a StorageClass

Create a StorageClass with a zone ID

Create storage-class.yaml with the following content:
```
kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: alicloud-disk-ssd-hangzhou-b
provisioner: alicloud/disk
parameters:
  type: cloud_ssd
  regionId: cn-hangzhou
  zoneId: cn-hangzhou-b
reclaimPolicy: Retain
```
Key parameters:
- provisioner: alicloud/disk — the volume plugin that provisions Alibaba Cloud disks
- type: cloud_ssd — disk type; valid values: cloud_efficiency (ultra disk), cloud_ssd (standard SSD), cloud_essd (Enhanced SSD (ESSD)), available (tries ESSD, then standard SSD, then ultra disk until one succeeds)
- regionId — region where the disk is created
- zoneId — zone where the disk is created; for multi-zone clusters, specify multiple zones as a comma-separated list (for example, cn-hangzhou-a,cn-hangzhou-b,cn-hangzhou-c)
- reclaimPolicy — what happens to the disk when the PV is released; default is Delete; set to Retain to prevent data loss from accidental deletion
- encrypted — (optional) whether to encrypt the disk; default is false
Apply the StorageClass:
```
kubectl apply -f storage-class.yaml
```

Verify the StorageClass was created:

kubectl get storageclass alicloud-disk-ssd-hangzhou-b

Create a StorageClass in WaitForFirstConsumer mode

WaitForFirstConsumer mode delays disk creation until a pod that uses the PVC is scheduled. The disk is created in the same zone as the scheduled pod, which avoids zone mismatch errors in multi-zone clusters.

Create storage-class-topology.yaml with the following content:
```
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: alicloud-disk-topology-ssd
provisioner: alicloud/disk
parameters:
  type: cloud_ssd
reclaimPolicy: Retain
volumeBindingMode: WaitForFirstConsumer
```
Key parameters:
- volumeBindingMode: WaitForFirstConsumer — delays disk creation until a pod that consumes the PVC is scheduled; the disk is created in the zone of the scheduled pod
- reclaimPolicy: Retain — preserves the disk when the PV is released; recommended for production workloads

Apply the StorageClass:

kubectl apply -f storage-class-topology.yaml

Verify the StorageClass was created:

kubectl get storageclass alicloud-disk-topology-ssd

Default StorageClasses for single-zone clusters

ACK pre-creates the following StorageClasses for single-zone clusters. For multi-zone clusters, create a StorageClass manually to specify the target zone.

StorageClass	Disk type
`alicloud-disk-efficiency`	Ultra disk
`alicloud-disk-ssd`	Standard SSD
`alicloud-disk-essd`	Enhanced SSD (ESSD)
`alicloud-disk-available`	High-availability mode: tries standard SSD first; falls back to ultra disk if SSD resources are exhausted. For alicloud-disk-controller versions earlier than v1.14.8.44-c23b62c5-aliyun, the fallback order is ESSD, standard SSD, then ultra disk.
`alicloud-disk-topology`	WaitForFirstConsumer mode

Create a PVC and pod

Create pvc-pod.yaml with the following content:

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: disk-ssd
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: alicloud-disk-ssd-hangzhou-b
  resources:
    requests:
      storage: 20Gi
---
kind: Pod
apiVersion: v1
metadata:
  name: disk-pod-ssd
spec:
  containers:
  - name: disk-pod
    image: nginx
    volumeMounts:
      - name: disk-pvc
        mountPath: "/mnt"
  restartPolicy: "Never"
  volumes:
    - name: disk-pvc
      persistentVolumeClaim:
        claimName: disk-ssd

Apply the manifest:
```
kubectl apply -f pvc-pod.yaml
```

Verify the PVC is bound and the pod is running:

kubectl get pvc disk-ssd
kubectl get pod disk-pod-ssd

A successfully bound PVC shows a Bound status:

NAME       STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS                    AGE
disk-ssd   Bound    pvc-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx   20Gi       RWO            alicloud-disk-ssd-hangzhou-b    1m

Create a StatefulSet with disk volumes

Use volumeClaimTemplates to automatically provision a separate PVC and PV for each StatefulSet replica.

Create statefulset.yaml with the following content:

apiVersion: v1
kind: Service
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  ports:
  - port: 80
    name: web
  clusterIP: None
  selector:
    app: nginx
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: web
spec:
  selector:
    matchLabels:
      app: nginx
  serviceName: "nginx"
  replicas: 2
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx
        ports:
        - containerPort: 80
          name: web
        volumeMounts:
        - name: disk-ssd
          mountPath: /data
  volumeClaimTemplates:
  - metadata:
      name: disk-ssd
    spec:
      accessModes: [ "ReadWriteOnce" ]
      storageClassName: "alicloud-disk-ssd-hangzhou-b"
      resources:
        requests:
          storage: 20Gi

Apply the manifest:
```
kubectl apply -f statefulset.yaml
```
Verify each replica has its own PVC:
```
kubectl get pvc -l app=nginx
kubectl get pods -l app=nginx
```
ACK creates one PVC per replica (for example, disk-ssd-web-0 and disk-ssd-web-1), each backed by a separate disk.

What's next

Use a dynamically provisioned disk volume in the ACK console