Use ENS disks-Container Service for Kubernetes(ACK)-阿里云帮助中心

Prerequisites

Before you begin, ensure that you have:

An ACK Edge cluster. See Create an ACK Edge cluster
An edge node created and added to the cluster. See Create an instance and Add an edge node
The csi-ens-plugin and csi-ens-provisioner components installed. See Manage components
A kubectl client connected to the cluster. See Obtain the kubeconfig file of a cluster and use kubectl to connect to the cluster
(Static provisioning only) A pay-as-you-go ENS disk already created. Record the disk ID — for example, d-wz92s6d95go6ki9x****

Choose a provisioning method

	Dynamic provisioning	Static provisioning
When to use	Deploying new applications that need storage	You already purchased an ENS disk
How the disk is created	Automatically via StorageClass	Manually, before creating the PV
Disk billing	Pay-as-you-go only	—
Typical setup	StorageClass → PVC → pod	PV → PVC → pod

Use dynamic provisioning for new deployments. Use static provisioning only when reusing an existing disk.

Usage notes

Hard constraints:

An ENS disk can be mounted to only one pod at a time. Sharing is not supported.
ENS disks can only be mounted to ENS nodes in the same region as the disk.
The only supported reclaimPolicy is Retain. Deleting a persistent volume claim (PVC) keeps the persistent volume (PV) and disk data intact — delete them manually when no longer needed.
allowVolumeExpansion is not supported.
To delete or reclaim an ENS disk, use the Edge Node Service console. You cannot do this from within the ACK cluster.
When a pod is recreated and the scheduler cannot place it in the original zone, the pod stays in Pending state until rescheduled to a compatible zone.

Recommendations:

For new deployments, use a StorageClass with dynamic provisioning to have ENS create and manage disks automatically.
Make sure the disk size does not exceed the per-disk capacity limit for the chosen disk type. See Disk types.
For billing details, see Billing of block storage devices.

Mount a dynamically provisioned ENS disk volume

Dynamic provisioning lets Kubernetes create and attach an ENS disk automatically when a pod needs storage. There are two binding modes — choose based on your cluster's region topology.

Step 1: Create a StorageClass

ACK Edge clusters can span multiple regions. Choose the binding mode that matches your deployment:

Binding mode	How it works	When to use
`WaitForFirstConsumer`	Creates the disk in the zone where the scheduled pod lands	Multi-region clusters (recommended)
`Immediate`	Creates the disk when the PVC is created, before any pod is scheduled	Single-region clusters or when the region is known in advance

Important

In multi-region ACK Edge clusters, use WaitForFirstConsumer to ensure the disk is created in the zone where the pod is scheduled.

Option A: WaitForFirstConsumer (recommended for multi-region clusters)

Create storage-class-topology.yaml:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: alicloud-ens-disk-available
provisioner: ensplugin.csi.alibabacloud.com
parameters:
  type: available
  fsType: ext4
volumeBindingMode: WaitForFirstConsumer
reclaimPolicy: Retain
allowVolumeExpansion: false

Key parameters:

provisioner: ensplugin.csi.alibabacloud.com — the ENS CSI provisioner that handles disk lifecycle.
type: available — the type of the disk.
volumeBindingMode: WaitForFirstConsumer — delays disk creation until a pod is scheduled, so the disk is created in the correct zone.
reclaimPolicy: Retain — the only supported value. The disk and its data persist after the PVC is deleted.

Apply the StorageClass:

kubectl apply -f storage-class-topology.yaml

Option B: Immediate (for single-region clusters)

Create storage-class-csi.yaml:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: alicloud-ens-disk-available
provisioner: ensplugin.csi.alibabacloud.com
parameters:
  type: available
  regionId: <your-region-id>
reclaimPolicy: Retain
allowVolumeExpansion: false
volumeBindingMode: Immediate

Key parameters:

regionId — optional. The region where the disk is automatically created.
volumeBindingMode: Immediate — creates the disk as soon as the PVC is created, before any pod is scheduled.

Apply the StorageClass:

kubectl apply -f storage-class-csi.yaml

Verify the StorageClass:

Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, click the cluster name. In the left-side pane, choose Volumes > StorageClasses.

The newly created StorageClass appears on the StorageClasses page.

Step 2: Create a PVC

Create pvc-ssd.yaml:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: disk-pvc
spec:
  accessModes:
  - ReadWriteOnce
  volumeMode: Filesystem
  resources:
    requests:
      storage: 25Gi
  storageClassName: alicloud-ens-disk-available

Apply the PVC:

kubectl create -f pvc-ssd.yaml

Verify the PVC:

In the left-side pane of the cluster details page, choose Volumes > Persistent Volume Claims. The PVC appears on the Persistent Volume Claims page.

Step 3: Create an application

Create pvc-dynamic.yaml to deploy an nginx StatefulSet that mounts the PVC:

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: nginx-dynamic
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx
        ports:
        - containerPort: 80
          name: web
        volumeMounts:
        - name: pvc-disk
          mountPath: /data
      volumes:
        - name: pvc-disk
          persistentVolumeClaim:
            claimName: disk-pvc

Key parameters:

mountPath: /data — the path inside the container where the disk is mounted.
claimName: disk-pvc — must match the PVC name from Step 2.

Apply the StatefulSet:

kubectl create -f pvc-dynamic.yaml

Verify the application:

In the left-side pane of the cluster details page, choose Workloads > StatefulSets. Confirm the nginx-dynamic StatefulSet is running.

Mount a statically provisioned ENS disk volume

Static provisioning is for cases where you have an existing pay-as-you-go ENS disk. You manually create a PV that references the disk ID, then bind a PVC to it.

Step 1: Create a PV

Create pv-static.yaml. Replace <your-disk-id> with your ENS disk ID and <your-node-region-id> with the region ID of the target ENS node:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: csi-pv
  labels:
    alicloud-pvname: static-disk-pv
spec:
  capacity:
    storage: 25Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  csi:
    driver: ensplugin.csi.alibabacloud.com
    volumeHandle: "<your-disk-id>"
  nodeAffinity:
    required:
      nodeSelectorTerms:
      - matchExpressions:
        - key: topology.ensplugin.csi.alibabacloud.com/region
          operator: In
          values:
          - "<your-node-region-id>"

Key parameters:

volumeHandle: "<your-disk-id>" — the ID of the ENS disk to associate with this PV. Example: d-wz92s6d95go6ki9x****.
nodeAffinity — constrains which nodes this PV can be bound to, based on region. Set <your-node-region-id> to the value of the topology.ensplugin.csi.alibabacloud.com/region label on the target ENS node.
labels: alicloud-pvname: static-disk-pv — used by the PVC selector in Step 2 to bind to this specific PV.
persistentVolumeReclaimPolicy: Retain — disk data is preserved when the PVC is deleted.

Apply the PV:

kubectl create -f pv-static.yaml

Verify the PV:

Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, click the cluster name. In the left-side pane, choose Volumes > Persistent Volumes.

The newly created PV appears on the Persistent Volumes page.

Step 2: Create a PVC

Create pvc-static.yaml. The matchLabels selector binds this PVC to the specific PV created in Step 1:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: csi-pvc
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 25Gi
  selector:
    matchLabels:
      alicloud-pvname: static-disk-pv

Key parameters:

storage: 25Gi — the requested capacity. Must not exceed the capacity of the PV being bound.
matchLabels: alicloud-pvname: static-disk-pv — selects the PV by its label. Must match the label on the PV from Step 1.

Apply the PVC:

kubectl create -f pvc-static.yaml

Verify the PVC:

In the left-side pane of the cluster details page, choose Volumes > Persistent Volume Claims. Confirm the csi-pvc PVC appears and is bound.

Step 3: Create an application

Create web.yaml to deploy an nginx StatefulSet mounted with the statically provisioned disk:

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: web
spec:
  selector:
    matchLabels:
      app: nginx
  serviceName: "nginx"
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx
        ports:
        - containerPort: 80
          name: web
        volumeMounts:
        - name: pvc-disk
          mountPath: /data
      volumes:
        - name: pvc-disk
          persistentVolumeClaim:
            claimName: csi-pvc

Key parameters:

mountPath: /data — the path inside the container where the disk is mounted.
claimName: csi-pvc — must match the PVC name from Step 2.

Apply the StatefulSet:

kubectl apply -f web.yaml

Verify the application:

In the left-side pane of the cluster details page, choose Workloads > StatefulSets. Confirm the web StatefulSet is running. A running status confirms the ENS disk is mounted successfully.

What's next

Disk types — compare disk type capacities and performance.
Billing of block storage devices — understand pay-as-you-go pricing for ENS disks.