By default, container storage is ephemeral — data written inside a container is lost when the container restarts. Mounting a disk volume lets data persist across restarts. This topic explains how to mount a disk as a volume when creating an elastic container instance via the CreateContainerGroup API.
Prerequisites
Before you begin, make sure that you have:
An elastic container instance in a target availability zone
A pay-as-you-go disk in the same availability zone as the instance (for static provisioning)
Limitations
Only pay-as-you-go disks can be mounted. See Block storage billing.
A disk can be mounted to only one elastic container instance at a time — disks cannot be shared.
Each elastic container instance supports a maximum of six disk volumes.
The disk must be in the same availability zone as the elastic container instance. Cross-zone mounting is not supported. Create the disk in the target zone before mounting.
NVMe disks with the multi-mount feature enabled (NVMe shared disks) cannot be mounted.
Disks that have partitions cannot be mounted. If you use a snapshot to create the disk and the snapshot-based disk has partitions, the disk also cannot be mounted.
How it works
Disk volumes use the FlexVolume plug-in with the alicloud/disk driver. When you call CreateContainerGroup, you:
Declare a volume using
Volume.N.*parameters — specifying the disk source (existing disk or new disk).Mount the declared volume to a container using
Container.N.VolumeMount.N.*parameters — specifying the mount path and behavior.
The two provisioning modes differ in how the disk is sourced:
| Mode | When to use | Key parameter |
|---|---|---|
| Static provisioning | You already have a disk to attach | volumeId in FlexVolume.Options |
| Dynamic provisioning | ECI creates a new disk at launch time | volumeSize in FlexVolume.Options |
Declare a volume
Set the following Volume.N.* parameters to declare a disk volume.
| Parameter | Type | Example | Description |
|---|---|---|---|
Volume.N.Name | String | disk-demo | The name of the volume. Referenced by Container.N.VolumeMount.N.Name when mounting. |
Volume.N.Type | String | FlexVolume | Set to FlexVolume to use the FlexVolume plug-in. |
Volume.N.FlexVolume.Driver | String | alicloud/disk | Set to alicloud/disk to mount an Alibaba Cloud disk. |
Volume.N.FlexVolume.FsType | String | ext4 | The file system type. Valid values: ext4, ext3, xfs, vfat. Default: ext4. |
Volume.N.FlexVolume.Options | String | {"volumeId":"d-bp1****"} | A JSON string containing the disk configuration. See the following sections for the available keys. |
Static provisioning — use an existing disk
Provide volumeId in FlexVolume.Options to attach an existing disk. The disk must be in the Pending state and in the same availability zone as the instance. When volumeId is specified, all other disk attribute parameters (volumeSize, performanceLevel, and so on) are ignored. If you do not specify volumeId, you must specify volumeSize.
| Option key | Description |
|---|---|
volumeId | The ID of the disk to attach. |
Dynamic provisioning — create a new disk
Omit volumeId and provide volumeSize to have ECI create a new disk at launch time. The system automatically uses an enhanced SSD (ESSD) — you cannot specify the disk category.
| Option key | Required | Description |
|---|---|---|
volumeSize | Yes | The disk size in GiB. Valid values: 20–32768. If you also specify snapshotId, the actual disk size is the greater of volumeSize and the size of the snapshot-based disk. |
performanceLevel | No | The performance level (PL) of the ESSD. See ESSDs. |
deleteWithInstance | No | Whether to release the disk when the instance is released. Default: true. |
encrypted | No | Whether to encrypt the disk. Default: false. See Encryption overview. |
kmsKeyId | No | The ID of the Key Management Service (KMS) key used for disk encryption. |
snapshotId | No | The ID of the snapshot to use when creating the disk. See Overview. |
tags | No | Tags to attach to the disk. Up to 20 tags. Format: "tagkey1:tagvalue1,tagkey2:tagvalue2". |
Mount a volume to a container
After declaring a volume, use Container.N.VolumeMount.N.* parameters to mount it to a container.
| Parameter | Type | Example | Description |
|---|---|---|---|
Container.N.VolumeMount.N.Name | String | disk-demo | The name of the volume to mount. Must match a Volume.N.Name value. |
Container.N.VolumeMount.N.MountPath | String | /data | The path inside the container where the volume is mounted. Existing data at this path is hidden by the volume. |
Container.N.VolumeMount.N.SubPath | String | /logs | A subdirectory of the volume to mount. Use this to mount different subdirectories of the same volume to different containers. |
Container.N.VolumeMount.N.ReadOnly | Boolean | false | Whether the mount path is read-only. Default: false. |
Container.N.VolumeMount.N.MountPropagation | String | None | Controls whether mounts are shared between containers and the host. Default: None. See the following table. |
Mount propagation modes
| Value | What the container sees | What the host sees |
|---|---|---|
None | Only mounts present at attach time — no subsequent mounts to this volume or its subdirectories are visible. | No mounts created inside the container are visible on the host. |
HostToContainer | All subsequent mounts made to this volume or its subdirectories on the host are visible inside the container. | No mounts created inside the container are visible on the host. |
Bidirectional | All subsequent mounts made to this volume or its subdirectories on the host are visible inside the container. | All mounts created inside the container are propagated back to the host and to all containers of all elastic container instances that use the same volume. |
To mount volumes to init containers, use the same parameters withInitContainerin place ofContainer.
Examples
The following examples show the key parameters to pass to CreateContainerGroup.
Example 1: Static provisioning (existing disk)
ContainerGroupName=test-disk1
SecurityGroupId=sg-bp1daxpbz9lzpvvc****
VSwitchId=vsw-bp1gds63lmlm7ib05****
# Declare the volume
Volume.1.Name=disk-demo
Volume.1.Type=FlexVolume
Volume.1.FlexVolume.Driver=alicloud/disk
Volume.1.FlexVolume.FsType=ext4
Volume.1.FlexVolume.Options={"volumeId":"d-2zebuamrpar7xnj****"}
# Mount the volume to the container
Container.1.Name=nginx
Container.1.Image=registry-vpc.cn-hangzhou.aliyuncs.com/eci_open/nginx:1.14.2
Container.1.VolumeMount.1.Name=disk-demo
Container.1.VolumeMount.1.MountPath=/dataThe disk must be in the Pending state and in the same availability zone as the instance before you run this operation.
Example 2: Dynamic provisioning (new disk)
ContainerGroupName=test-disk2
# Declare the volume
Volume.1.Name=disk-demo
Volume.1.Type=FlexVolume
Volume.1.FlexVolume.Driver=alicloud/disk
Volume.1.FlexVolume.FsType=ext4
Volume.1.FlexVolume.Options={"volumeSize":"50","tags":"test:eci"}
# Mount the volume to the container
Container.1.Name=nginx
Container.1.Image=registry-vpc.cn-hangzhou.aliyuncs.com/eci_open/nginx:1.14.2
Container.1.VolumeMount.1.Name=disk-demo
Container.1.VolumeMount.1.MountPath=/dataA 50 GiB ESSD is created automatically when the instance launches. The disk is released with the instance by default (deleteWithInstance: true).