Enable Persistent Storage on ACK Edge Nodes with ENS Disk CSI - Container Service for Kubernetes

Edge Node Service (ENS) disks provide block storage for ENS nodes in ACK Edge clusters. Using the Container Storage Interface (CSI) driver, you can mount ENS disk volumes through two approaches: dynamic provisioning, where the cluster automatically creates a disk when a PersistentVolumeClaim (PVC) is created; and static provisioning, where you manually bind a pre-existing disk to a PersistentVolume (PV).

Prerequisites

Before you begin, make sure 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 edge nodes.
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, with its disk ID recorded.

Considerations

Hard limits:

ENS disks cannot be shared. A disk can be mounted to only one Pod at a time.
ENS disks can only be mounted to ENS nodes in the same region as the disk.
The only supported reclaim policy is Retain. When you delete a PVC, the PV and disk data are retained and must be deleted manually in the Edge Node Service console.
When a Pod is recreated, the system remounts the original disk. If the Pod cannot be scheduled to the original zone, it remains in the Pending state.
Dynamic provisioning supports only pay-as-you-go disks. For billing details, see Billing overview.For more information about billing, see Billing of block storage. For pricing details, see the ECS product page.
The disk size you specify must fall within the capacity range for the disk type. See Disk types.

How it works

Dynamic provisioning:

You create a StorageClass with the ENS CSI provisioner and a PVC that references it.
When a Pod is scheduled, the CSI driver creates an ENS disk in the zone where the node resides.
The CSI driver provisions a PV and binds it to the PVC.
The disk is attached to the node and mounted into the Pod.

Static provisioning:

You create a PV that references an existing ENS disk ID.
You create a PVC with a label selector that matches the PV.
Kubernetes binds the PVC to the PV.
You deploy a workload that references the PVC, and the disk is mounted into the Pod.

Use dynamic provisioning

Dynamic provisioning automates disk creation and PV binding. Use a StorageClass to provision ENS disks on demand.

Step 1: Create a StorageClass

ENS CSI supports two volume binding modes. Choose one based on your deployment:

Binding mode	Behavior	Use when
`WaitForFirstConsumer` (recommended)	Delays disk creation until a Pod is scheduled; creates the disk in the Pod's zone	Your cluster spans multiple regions
`Immediate`	Creates a disk immediately when the PVC is created	Your cluster is in a single region and you specify `regionId`

Option 1: WaitForFirstConsumer (recommended)

Create a file named storage-class-topology.yaml with the following content:

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

Apply the StorageClass:

kubectl apply -f storage-class-topology.yaml

Verify the StorageClass was created:

kubectl get storageclass alicloud-ens-disk-available

Option 2: Immediate

Create a file named storage-class-csi.yaml with the following content:

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

Apply the StorageClass:
```
kubectl apply -f storage-class-csi.yaml
```

Verify the StorageClass was created:

kubectl get storageclass alicloud-ens-disk-available

StorageClass parameters:

Parameter	Values	Default	Description
`provisioner`	`ensplugin.csi.alibabacloud.com`	—	ENS CSI driver identifier. Must be set to this value.
`type`	`available`	—	Disk type to provision.
`fsType`	`ext4`	`ext4`	Filesystem type to create on the disk.
`regionId`	A valid ENS region ID	—	Optional. The region where the disk is automatically created.
`reclaimPolicy`	`Retain`	`Retain`	Disk reclaim policy. Only `Retain` is supported.
`volumeBindingMode`	`WaitForFirstConsumer`, `Immediate`	`Immediate`	Controls when disk creation and PV binding occur.
`allowVolumeExpansion`	`false`	`false`	Volume expansion is not supported.

Step 2: Create a PVC

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

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-dynamic.yaml
```
Verify the PVC status:
```
kubectl get pvc disk-pvc
```
If you used WaitForFirstConsumer, the PVC remains in Pending until a Pod that references it is scheduled. This is expected behavior.

Step 3: Deploy a workload

Create a file named pvc-dynamic-workload.yaml with the following content:

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: /tmp
      volumes:
        - name: pvc-disk
          persistentVolumeClaim:
            claimName: disk-pvc

Parameter	Description
`mountPath`	Path inside the container where the disk is mounted.
`claimName`	Name of the PVC to mount. Must match the PVC created in the previous step.

Apply the StatefulSet:

kubectl create -f pvc-dynamic-workload.yaml

Verify the Pod is running and the PVC is bound:
```
kubectl get pods -l app=nginx
kubectl get pvc disk-pvc
```
The PVC status changes to Bound after the Pod is scheduled and the disk is provisioned. Pod scheduling may take a few minutes.

Use static provisioning

Static provisioning lets you mount a pre-existing ENS disk into your workload. Use this approach when you have already created and configured a disk.

Step 1: Create a PV

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

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>"    # Replace with your ENS disk ID
  nodeAffinity:
    required:
      nodeSelectorTerms:
      - matchExpressions:
        - key: topology.ensplugin.csi.alibabacloud.com/region
          operator: In
          values:
          - "<your-node-region-id>"  # Run: kubectl get node <node-name> --show-labels

Parameter	Description
`volumeHandle`	The disk ID of the existing ENS disk. Find this in the Edge Node Service console.
`nodeAffinity`	Restricts the PV to nodes in the specified region. Set to the region of the ENS disk.
`topology.ensplugin.csi.alibabacloud.com/region`	The region ID of the ENS node. Run `kubectl get node <node-name> --show-labels` to find this value.

Apply the PV:
```
kubectl create -f pv-static.yaml
```
Verify the PV was created:
```
kubectl get pv csi-pv
```

Step 2: Create a PVC

Create a file named pvc-static.yaml with the following content:
```
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: csi-pvc
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 25Gi
  storageClassName: ""
  selector:
    matchLabels:
      alicloud-pvname: static-disk-pv
```
The storageClassName: "" tells Kubernetes to bind to a manually created PV rather than using dynamic provisioning. The selector.matchLabels must match the labels on the PV. The claimed storage (25Gi) cannot exceed the PV capacity.
Apply the PVC:
```
kubectl create -f pvc-static.yaml
```
Verify the PVC is bound to the PV:
```
kubectl get pvc csi-pvc
```
The PVC status should show Bound.

Step 3: Deploy a workload

Create a file named web-static.yaml with the following content:

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: nginx-static
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: /tmp
      volumes:
        - name: pvc-disk
          persistentVolumeClaim:
            claimName: csi-pvc

Apply the StatefulSet:
```
kubectl apply -f web-static.yaml
```
Verify the Pod is running:
```
kubectl get pods -l app=nginx
kubectl get pvc csi-pvc
```
When the Pod reaches Running status and the PVC shows Bound, the ENS disk is successfully mounted.

What's next

Manage components — Update or uninstall the csi-ens-plugin and csi-ens-provisioner components.
Disk types — Review available ENS disk types and their capacity ranges.
Billing overview — Understand ENS disk billing for dynamically provisioned volumes.