Kubernetes storage basics-Container Service for Kubernetes(ACK)-阿里云帮助中心

Volumes

Container filesystems are ephemeral—files are lost on restart. Volumes define external storage in the pod spec; Kubernetes mounts it into containers at runtime.

ACK supports the following volume types:

Type	Description
Local storage	Node-local volumes such as `hostPath` and `emptyDir`. Data is tied to the node and lost if it goes down. Not for stateful workloads that may reschedule.
Network storage	Remote volumes such as Ceph, GlusterFS, NFS, and iSCSI. Data resides on a remote service, but the service must be mounted locally.
Secret and ConfigMap	Special volumes that expose cluster object data (credentials, configuration) to pods as files.
PVC	A volume backed by a PersistentVolumeClaim that abstracts storage as an independent object. Use for durable, portable storage.

Usage notes:

A pod can mount multiple volumes, including different types.
All containers in a pod share its mounted volumes.
A volume shares the pod's lifecycle. Data persistence after pod deletion depends on the volume type and configuration.
For durable data, use PVCs and PVs.

PVs and PVCs

Not all Kubernetes volumes are persistent. For durable storage, Kubernetes introduces two objects that separate how storage is provisioned from how storage is consumed :

A PV is a cluster storage resource, analogous to a node: pods consume nodes, and PVCs consume PVs. A PV has its own lifecycle, independent of any pod.
A PVC is a request for storage, analogous to a pod: just as a pod requests CPU and memory from a node, a PVC requests capacity and access modes from a PV.

Developers declare storage needs (PVC) while administrators manage provisioning (PV).

PV example

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-example
spec:
  capacity:
    storage: 20Gi # adjust to match the actual cloud disk size
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  csi:
    driver: diskplugin.csi.alibabacloud.com
    volumeHandle: <disk ID>
  volumeMode: Filesystem

PVC example

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-example
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi
  volumeName: pv-example

Binding rules

PVs and PVCs have a one-to-one relationship: exactly one PVC binds to each PV. Before a PVC can be used by a pod, Kubernetes must find a PV that satisfies the following:

Field	Requirement
`volumeMode`	Must match the PVC's volume mode
`accessModes`	Must include the access modes requested by the PVC
`storageClassName`	If specified in the PVC, the PV must have the same StorageClass
Label selector	The PV must match any label selector defined in the PVC
`storage`	The PV's capacity must be at least the amount requested by the PVC

How the storage field works:

Kubernetes uses storage to match and bind PVs to PVCs.
In dynamic provisioning, the PVC's storage value sets the capacity of the PV and underlying resource (such as a cloud disk).
For storage types that support resizing, the PVC's storage value sets the target capacity after a scale-out.
storage is a logical capacity declaration. Actual writable capacity depends on the underlying storage medium, not on the storage field.

Volume access modes

Use the accessModes field to define how a volume can be mounted:

Access mode	Abbreviation	Description	Example
ReadWriteOnce	RWO	Read-write by a single node	Alibaba Cloud disk
ReadOnlyMany	ROX	Read-only by multiple nodes	OSS bucket
ReadWriteMany	RWX	Read-write by multiple nodes	NAS file system

How volumes are provisioned

ACK supports two provisioning workflows: static and dynamic.

Static provisioning

In static provisioning, the cluster administrator creates PVs in advance. Cloud disks, NAS file systems, and OSS buckets support static provisioning.

The administrator allocates storage resources (e.g., cloud disks or NAS file systems) based on pod requirements.
The administrator creates PVs describing those resources, including capacity and configuration.
Developers create PVCs that declare what their workloads need.
When a pod is created, Kubernetes binds the PVC to a matching PV.

Dynamic provisioning

In dynamic provisioning, a CSI provisioner creates PVs automatically when a PVC is created. Cloud disks, NAS file systems, and OSS buckets support dynamic provisioning.

The administrator creates a StorageClass that defines the storage type and provisioner. For example, diskplugin.csi.alibabacloud.com provisions cloud disks.
Developers create PVCs referencing a StorageClass. No manual PV creation needed.
When a pod is created, the CSI provisioner reads the StorageClass, creates a PV and the underlying storage resource, and binds the PV to the PVC.

Dynamic provisioning offers three advantages:

Automated lifecycle management: the provisioner handles PV creation and deletion automatically.
Reduced operational burden: administrators manage StorageClasses rather than individual PVs.
Capacity consistency: the PV and underlying resource always match the PVC's requested capacity.

StorageClasses

A StorageClass defines the storage type, provisioner, and parameters used for dynamic provisioning. When a PVC references a StorageClass and no matching PV exists, Kubernetes triggers the provisioner to create a PV and underlying storage automatically.

StorageClass example

The following StorageClass provisions Alibaba Cloud disks:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: alicloud-disk-topology-alltype
provisioner: diskplugin.csi.alibabacloud.com
parameters:
  type: cloud_auto,cloud_essd,cloud_ssd,cloud_efficiency
  fstype: ext4
  diskTags/a: b
  encrypted: "false"
  performanceLevel: PL1
  provisionedIops: "40000"
  burstingEnabled: "false"
reclaimPolicy: Delete
allowVolumeExpansion: true
volumeBindingMode: WaitForFirstConsumer

Key parameters

Parameter	Description
`provisioner`	The CSI driver for storage provisioning. Use `diskplugin.csi.alibabacloud.com` for cloud disks, `nasplugin.csi.alibabacloud.com` for NAS, or `ossplugin.csi.alibabacloud.com` for OSS.
`parameters`	Driver-specific parameters, such as disk type, filesystem type, and performance settings.
`reclaimPolicy`	What happens to the PV and underlying storage when the PVC is deleted. `Delete` (default) removes both the PV and the cloud disk. `Retain` keeps both—you must delete them manually. Set to `Retain` if data security is a priority.
`allowVolumeExpansion`	Set to `true` to enable online disk expansion.
`volumeBindingMode`	When the PV is provisioned. See the table below.

Choosing a volumeBindingMode:

Mode	When the PV is created	Recommended for
`Immediate` (default)	When the PVC is created, before any pod is scheduled	Single-zone clusters
`WaitForFirstConsumer`	After a pod that uses the PVC is scheduled to a node	Multi-zone clusters

Use WaitForFirstConsumer in multi-zone clusters. Cloud disks cannot be mounted across zones. If a PV is in Zone A but a pod is scheduled to Zone B, the pod fails to start. With WaitForFirstConsumer, the provisioner waits for pod scheduling, then creates the disk in the pod's zone.

How WaitForFirstConsumer works:

When a PVC is created, the provisioner waits until a pod consumes it. The scheduler places the pod on a node and writes the result (region and node) to the PVC metadata. The provisioner then creates the PV and disk in the correct zone.

Default StorageClass

A default StorageClass automatically provisions a PV for any PVC that omits a StorageClass name.

Important

ACK clusters do not include a default StorageClass. A default StorageClass applies to all PVCs without a storageClassName. If your cluster uses multiple storage types, it may provision the wrong type. Enable only if all PVCs use the same storage type.

Set a default StorageClass:

Mark alicloud-disk-topology-alltype as the default:

kubectl annotate storageclass alicloud-disk-topology-alltype storageclass.kubernetes.io/is-default-class=true

Verify the change:

kubectl get sc

Expected output:

NAME                                        PROVISIONER                       AGE
alicloud-disk-topology-alltype (default)    diskplugin.csi.alibabacloud.com   96m

Create a PVC without specifying a StorageClass:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: disk-pvc
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi

The cluster automatically creates a cloud disk PV using alicloud-disk-topology-alltype.

kubectl get pvc

Expected output:

NAME       STATUS   VOLUME                   CAPACITY   ACCESS MODES    STORAGECLASS                      AGE
disk-pvc   Bound    d-bp18pbai447qverm****   20Gi       RWO             alicloud-disk-topology-alltype    49s

Remove the default StorageClass:

kubectl annotate storageclass alicloud-disk-topology-alltype storageclass.kubernetes.io/is-default-class-

StorageClasses provided by ACK

StorageClass	Disk type	Notes
`alicloud-disk-efficiency`	Ultra disk	Previous-generation cloud disk
`alicloud-disk-ssd`	Standard SSD	Previous-generation cloud disk
`alicloud-disk-essd`	ESSD	Performance Level 1 (PL1) Enterprise SSD
`alicloud-disk-topology-alltype`	Multi-type	Attempts ESSD first, then standard SSD, then ultra disk. Recommended for multi-zone clusters.
`alibabacloud-cnfs-nas`	CNFS-managed NAS	Creates Container Network File System (CNFS)-managed NAS volumes

The alicloud-disk-topology-alltype StorageClass selects the best available disk type:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: alicloud-disk-topology-alltype
parameters:
  type: cloud_essd,cloud_ssd,cloud_efficiency
provisioner: diskplugin.csi.alibabacloud.com
reclaimPolicy: Delete
allowVolumeExpansion: true
volumeBindingMode: WaitForFirstConsumer

Next steps

See Storage for all storage types and guides.

To provision specific storage types: