Configure storage for containerized applications in ACK - Container Service for Kubernetes

Kubernetes applications often require persistent storage to store data. Alibaba Cloud Container Service for Kubernetes (ACK) integrates multiple Alibaba Cloud storage services—such as Elastic Block Storage (EBS), Object Storage Service (OSS), Network Attached Storage (NAS), and Cloud Parallel File Storage (CPFS)—through the standard Container Storage Interface (CSI). ACK is also compatible with native Kubernetes storage mechanisms to provide tailored storage solutions for different business scenarios.

Select a storage solution

ACK provides two types of storage solutions:

Kubernetes-native volumes: Designed for temporary data, configuration management, or node-level interaction. Their lifecycle is tied to that of a pod, and they do not support data persistence for applications.
Alibaba Cloud persistent volumes: Integrated through Container Storage Interface (CSI) components, these volumes provide stable and reliable data persistence for workloads. Their lifecycle is independent of pods and they support stateful applications.

Before you use container storage, make sure that you understand key concepts such as volume, PersistentVolume (PV), and PersistentVolumeClaim (PVC). For more information, see Storage basics.

Kubernetes-native volumes

Kubernetes-native volumes have lifecycles that are bound to pods and are not suitable for persisting application data.

Type	Description	Key feature
emptyDir	A temporary empty directory whose lifecycle matches that of its pod.	Data is lost when the pod is deleted. Use this for inter-container data exchange or temporary caching within a pod.
HostPath	Mounts a file or directory from the host node into a pod. You can control pre-mount checks and creation behavior using the `type` field (for example, `DirectoryOrCreate`). For more information, see HostPath volumes	Data is bound to the node and does not move with the pod. Not suitable for stateful applications requiring high availability and persistence (for example, databases or caches).
ConfigMap/Secret	Mounts configuration items or sensitive credentials as files.	Designed only for small-volume configuration data—not business data. Used to decouple configuration from applications.

Alibaba Cloud persistent volumes

For stateful applications that require persistent data storage, you can use Alibaba Cloud persistent volumes. These volumes have lifecycles that are independent of pods and are integrated with Kubernetes using CSI.

Solution comparison

To help you select the right option quickly, each storage solution in the table below includes quick-reference icons for core attributes. For example, for EBS:

Cloud disk: Solution details. Click (view details) to view details.
Static/Dynamic: The supported volume provisioning methods, including static provisioning (PV/PVC) and dynamic provisioning (StorageClass/PVC). Click the links for step-by-step instructions.
RWO: The supported access modes (accessModes): RWO (ReadWriteOnce), RWX (ReadWriteMany), and ROX (ReadOnlyMany).
Billing: Billing details. Click the link to view details.

Storage option	Description	Trade-offs and limits
cloud disk ^Static^/^Dynamic^\|^{RWO (multi-attach disabled)}^\|^Billing	Description: A block storage service that delivers high data reliability (99.9999999%) and consistent I/O performance. Data is stored redundantly across three replicas in the backend. EBS supports both filesystem mode (`volumeMode: Filesystem`) and raw block device mode (`volumeMode: Block`). EBS offers multiple performance tiers (ESSD AutoPL, ESSD, and ESSD Entry) and at-rest encryption. Use case: Ideal for single-instance, stateful applications with strict I/O and data reliability requirements, such as MySQL or PostgreSQL databases and Redis or Elasticsearch middleware.	`accessModes` limit: An EBS disk without multi-attach enabled can be mounted to only one pod at a time. It cannot natively meet the business needs that require shared data across multiple instances, such as content sharing in a web cluster. We recommend that you use EBS for StatefulSet or single-pod deployments. Do not use EBS for multi-replica Deployments. For more information, see the operation guide. Zone binding: Except for regional Enterprise SSD (ESSD) disks, all other EBS disk types can be mounted only to pods in the same zone. We recommend that you use a `WaitForFirstConsumer` StorageClass to enable topology-aware scheduling. Instance compatibility: EBS disk types must be compatible with the supported ECS instance families. For more information, see instance families.
NAS ^Static^/^Dynamic^{\| RWX, RWO, ROX \|}^Billing	Description: A shared file storage service that supports the NFS protocol. NAS allows concurrent read/write access by multiple pods. It provides elastic scaling for capacity and performance and includes data protection features such as a recycle bin, snapshots, and backups. Use case: Content sharing across web clusters, CI/CD pipelines, centralized log storage, and any scenario where multiple application instances need concurrent read/write access to the same dataset.	Network I/O overhead: All reads and writes go over the network, which adds extra millisecond-scale latency compared to EBS. This solution is not recommended for latency-sensitive applications such as databases. Neighbor noise: In subpath or sharepath shared instances, dynamically provisioned PVs map to subdirectories of the same NAS backend. This may cause contention for shared bandwidth and IOPS. Protocol and network limits: Supports only the NFS protocol and does not allow cross-VPC mounting.
OSS ^Static ^{ossfs 1.0}^/^{ossfs 2.0} ^Dynamic ^{ossfs 1.0}^/^{ossfs 2.0} ^{RWX, ROX \|}^Billing	Description: A massive-scale, low-cost object storage service. Using the `ossfs` tool, you can mount an OSS bucket as a filesystem inside a pod. OSS offers two mounting options: `ossfs 1.0`, which prioritizes POSIX compliance, and `ossfs 2.0`, which is optimized for high throughput and concurrency. Use case: AI and big data analytics data lakes, static media assets such as images and videos for websites, and application data backup and archiving.	Non-native performance: Implemented using Filesystem in Userspace (FUSE), which converts filesystem operations into HTTP API calls. This results in high latency and poor random I/O performance. This solution is not recommended for databases or high-frequency write workloads. Incomplete POSIX compliance: Does not fully support all standard filesystem operations. For example, `chmod` and `chown` on the root path are restricted. This may cause application compatibility issues.
CPFS for Lingjun ^Static^/^Dynamic^{\| RWX \|}^Billing	Description: A high-performance parallel file system built specifically for AI and intelligent computing. It delivers exceptional throughput and IOPS for parallel I/O workloads. Use case: AI-Generated Content (AIGC) large-model training and inference and autonomous driving simulation. These scenarios demand extreme parallel I/O performance.	Cost and availability: This is a high-cost solution that is designed for specific high-performance use cases. This solution is currently in invitational preview and available only in selected regions. Mounting limit: Does not support cross-VPC mounting.
CPFS General Edition ^Static^{\| RWX \|}^Billing	Description: A shared file system built for high-performance computing (HPC) workloads. It delivers higher IOPS and throughput than General-purpose NAS. Use case: Genomic computing, big data analytics, and data cache acceleration in traditional HPC domains.	Cost and availability: This solution has a higher cost than General-purpose NAS and is available only in selected regions. Mounting limit: Supports only the NFS protocol and does not allow cross-VPC mounting.

Beyond basic performance, storage options differ in operational areas such as fault recovery, capacity management, and data protection. Consider the following questions to refine your selection.

How do applications and data recover when a node that hosts a pod fails?

Fast application recovery and data safety during node failure are central to a high-availability architecture.

EBS: The CSI driver automatically detaches the disk from the failed node and attaches it to a new node.
NAS, OSS, and CPFS: As shared storage, pods can be remounted immediately after they start on a new node. You do not need to wait for storage failover. The recovery speed depends only on the application startup time.
HostPath: Data is fixed to a specific node. If that node fails, the pod cannot start on another node and access its original data. Cross-node data replication and high availability must be handled by the application itself.

Selection guidance: We recommend that you choose EBS if your application, such as a single-instance database, can tolerate minute-level interruptions. For fast failover, such as for highly available web services, prioritize shared storage with multi-replica deployments. Choose local disks only if your application handles data replication and high availability, and you need maximum performance.

How do you plan and manage storage capacity for your applications?

Thoughtful capacity planning helps control costs and prevents service interruptions that are caused by exhausted storage. The effect of PVC capacity requests varies across storage types.

Cloud disk: The capacity declared in a PVC corresponds one-to-one with the capacity of the allocated cloud disk. The capacity limit is enforced, and online expansion is supported. This is suitable for scenarios that require clear capacity requirements and strict resource isolation.
OSS: No hard capacity limit. You pay only for actual usage. The PVC capacity is used only for matching PVs, not for enforcing usage limits.
NAS and CPFS:
- Static volumes: The PVC capacity is used only for matching PVs, not for limiting actual usage. The available capacity depends on the total capacity of the backend instance, which is shared across all pods.
- Dynamic volumes: For NAS (subpath only, with allowVolumeExpansion set to true) and CPFS for Lingjun, the PVC capacity translates to a quota on the corresponding directory, which enforces actual capacity limits. In all other cases, the behavior matches that of static volumes.

Selection guidance: We recommend that you use EBS for applications that require precise capacity budgets and strong isolation, such as multi-tenant databases. We recommend that you use shared storage for workloads with many pods that share data and have variable capacity needs, such as logs or static web files.

How do you back up application data to prevent accidental deletion or corruption?

EBS: You can use snapshots to create and restore entire volumes in seconds. EBS also supports backup schedules and on-demand backups to reduce the risk of data loss.
NAS: Offers a recycle bin through Container Network File System (CNFS), which supports the restoration of individual files or directories, and snapshots, which are supported on some NAS types.
OSS: Provides versioning and lifecycle management to prevent accidental operations and support data archiving.
HostPath: Data protection relies entirely on application-layer high availability and replication.

Selection guidance: We recommend that you use EBS snapshots for fast and consistent full-volume backup and restoration. We recommend that you use NAS or OSS features for long-term archiving, compliance audits, or restoring individual files. If you use HostPath, you must ensure that your application implements robust data protection.

Key components and concepts

CSI components (csi-plugin, csi-provisioner)
These components are the Kubernetes community-recommended implementation for storage plugins. They are pre-installed and enabled by default in ACK clusters. The components interact with Alibaba Cloud storage APIs to manage the full lifecycle of volumes, including automatic creation, mounting, and unmounting. For more information, see Manage CSI components.
Container Network File System (CNFS)
CNFS is an enhanced storage capability that is available in ACK Pro clusters. It abstracts NAS, OSS, and CPFS as Kubernetes Custom Resource Definitions (CRDs) to enable fine-grained management, such as dynamic subdirectory creation, quota management, I/O performance monitoring, recycle bin management, and distributed caching. For more information, see Container Network File System (CNFS).

Usage notes

When you use CSI, take note of the following limits.

Cluster version: Your cluster must run Kubernetes 1.14 or later. To upgrade your cluster, see Manually upgrade a cluster.
Cluster environment: CSI is fully tested and validated in ACK clusters. For non-ACK clusters, such as clusters in non-Alibaba Cloud environments or self-managed clusters on Alibaba Cloud, CSI may not provide out-of-the-box functionality due to differences in configurations, permissions, and networking.
We recommend that you review the alibaba-cloud-csi-driver source code and adapt it to your environment.
Node configuration: The kubelet parameter --enable-controller-attach-detach must be set to true.
Operating system: Windows nodes are not supported.
RBAC permissions: PersistentVolumes (PVs) are cluster-scoped resources. PersistentVolumeClaims (PVCs) are namespace-scoped. When you grant RBAC permissions, take note of the different access levels that are required for these two resource types.
If the default ACK roles, such as administrator and O&M engineer, do not meet your needs, you can configure custom permissions. For example, the default O&M engineer role grants read and write access to PVCs in authorized namespaces but only read-only access to PVs across the cluster. Therefore, you cannot use this role to manually create PVs. For more information, see Grant RBAC permissions to a RAM user or RAM role.

FAQ

How do I check which storage plugin my cluster uses?

You can use one of the following methods.

Check node annotations in the ACK console

On the ACK Clusters page, click the name of your cluster. On the cluster details page, in the navigation pane on the left, click Nodes > Nodes.
In the node list, find the node that you want to manage and click Details in the Actions column. On the Overview tab, view the Annotations of the node.
If volumes.kubernetes.io/controller-managed-attach-detach: true exists, the storage plugin is CSI. If it does not exist, the plugin is FlexVolume.

View kubelet parameters with a command

Log on to a node and check the kubelet parameters.

ps -ef | grep kubelet

Expected output:

--enable-controller-attach-detach=true

true: The storage plugin is CSI.
false: The storage plugin is FlexVolume.

How do I manually grant permissions to the CSI plugin?

The CSI plugin requires permissions to access other cloud resources when it mounts, unmounts, creates, or deletes volumes. By default, CSI is installed and configured with the required permissions in ACK clusters. To manually set up permissions, perform the following steps.

Grant permissions using a RAM role (default): The CSI plugin uses the AliyunCSManagedCsiRole to access resources in other Alibaba Cloud services. For more information, see ACK service roles.
- ACK managed clusters: For ACK managed clusters, the token for the RAM role that is used by CSI is stored in a Secret named addon.csi.token. You can mount this Secret to grant permissions and enable API access.
- ACK dedicated clusters: For ACK dedicated clusters, CSI inherits the RAM role that is assigned to the ECS node on which its pod runs.
For more information about how to grant permissions to RAM roles, see Manage permissions for a RAM role.
Grant permissions using an AccessKey pair
- Use environment variables: You can create the AccessKey pair as a Kubernetes Secret and inject it into the CSI pod as an environment variable. This prevents credentials from being exposed in plain text in deployment templates.
- Use a direct YAML entry: You can embed the AccessKey pair directly in the CSI YAML file. This method is not recommended for production environments.

Container Service for Kubernetes:Storage overview