All Products
Search

This Product

    Elastic Container Instance:Mount an OSS volume to an elastic container instance

    Document Center

    Elastic Container Instance:Mount an OSS volume to an elastic container instance

    Last Updated:Jun 20, 2026

    Object Storage Service (OSS) provides massive-scale, secure, cost-effective, and highly reliable storage for unstructured data such as images, audio files, and video files. This topic describes how to mount an OSS volume to an elastic container instance.

    Usage notes

    • OSS is billed based on usage and supports billing methods such as pay-as-you-go, resource plans, and storage capacity units (SCUs). For more information, see OSS billing overview.

    • OSS provides shared storage. A single OSS bucket can be mounted to multiple instances.

    • Store no more than 1,000 files in a single mount directory.

      An excessive number of files can cause the OSS client to consume a large amount of memory, which may lead to an OOM (out-of-memory) event for the instance.

    Prerequisites

    1. Create an OSS bucket.

      1. Log on to the OSS console.

      2. Create an OSS bucket.

        For more information, see Create buckets.

    2. Choose an authorization method.

      • Use a RAM role for authorization (Recommended).

        Create a RAM role and grant permissions to it. For more information, see Create a RAM role and Grant permissions to a RAM role.

        When you create the role, set Trusted Entity Type to Alibaba Cloud Service, Role Type to Normal Service Role, and Trusted Service to Elastic Compute Service (ECS). Attach the AliyunOSSFullAccess policy to the role.

      • Use an AccessKey pair for authorization (Not recommended).

        Obtain an AccessKey ID and an AccessKey Secret. For more information, see Obtain an AccessKey pair.

    Configuration (API)

    When you call the CreateContainerGroup API operation to create an elastic container instance, you can use Volume-related parameters to specify volumes, and then use Container.VolumeMount-related parameters to mount the volumes to containers. The relevant parameters are described below. For more information, see CreateContainerGroup.

    Declare a volume

    When you use Volume-related parameters to specify volumes, you must first specify the types and names of the volumes. Then, you must configure other Volume-related parameters based on the value of the Volume.N.Type parameter.

    Parameter

    Type

    Example

    Description

    Volume.N.Name

    String

    oss-demo

    The name of the volume.

    Volume.N.Type

    String

    FlexVolume

    Set to FlexVolume to create a volume mounted using a FlexVolume plug-in.

    Volume.N.FlexVolume.Driver

    String

    alicloud/oss

    The FlexVolume plug-in driver. Set to alicloud/oss to mount an OSS volume.

    Volume.N.FlexVolume.Options

    String

    {"bucket":"test-*","url":"oss-cn-hangzhou.aliyuncs.com","ramRole":"ram-*"}

    A JSON string of options for the FlexVolume object.

    When you use FlexVolume to mount an OSS volume, the Options parameter specifies the configuration of the OSS volume. The following parameters are supported:

    • bucket: The name of the OSS bucket.

    • url: The endpoint of the OSS bucket. You can obtain the endpoint from the Overview page of the target bucket in the OSS console. For more information, see Regions and endpoints.

    • path: The directory path relative to the root directory of the bucket. Default value: /.

    • otherOpts: Custom parameters that you can specify when you mount an OSS volume. The format is -o *** -o ***. Example: -o max_stat_cache_size=0 -o allow_other.

    • akId: The AccessKey ID if you use an AccessKey pair for authorization.

    • akSecret: The AccessKey Secret if you use an AccessKey pair for authorization.

    • ramRole: The name of the RAM role if you use a RAM role for authorization.
    Mount volumes

    After you specify volumes, you can use VolumeMount-related parameters to mount the volumes to containers.

    Parameter

    Type

    Example

    Description

    Container.N.VolumeMount.N.Name

    String

    test-volume

    The name of volume N to be mounted to container N. This value is the value of Volume.N.Name.

    Container.N.VolumeMount.N.MountPath

    String

    /usr/share

    The path within the container at which to mount the volume. Data in this directory is obscured by the data on the volume.

    Container.N.VolumeMount.N.SubPath

    String

    /usr/sub

    The subdirectory of the volume. This parameter specifies different subdirectories of the same volume that the instance can mount to different subdirectories of containers.

    Container.N.VolumeMount.N.ReadOnly

    Boolean

    false

    Specifies whether the mount directory is read-only. Default value: false.

    Container.N.VolumeMount.N.MountPropagation

    String

    None

    The mount propagation setting of volume N. Mount propagation allows you to share volumes that are mounted to one container to other containers in the same elastic container instance, or even to other elastic container instances on the same host. Valid values:

    • None: The volume mount does not receive subsequent mounts that are mounted to this volume or its subdirectories.

    • HostToContainer: The volume mount receives all subsequent mounts that are mounted to this volume or its subdirectories.

    • Bidirectional: This value has a similar effect as HostToContainer. The volume mount receives all subsequent mounts that are mounted to this volume or its subdirectories. In addition, all volume mounts created by container N are propagated back to the host and to all containers of all elastic container instances that use the same volume.

    Default value: None.

    Note

    Volumes can also be mounted to init containers. The required parameters are similar to the parameters in the preceding table. You only need to change Container to InitContainer.

    Configuration (Console)

    When you create an elastic container instance on the Elastic Container Instance buy page, you can specify volumes in the Container Group Configurations section and then mount the volumes to containers in the Container Configurations section.

    Declare a volume

    1. In the Container Group Configurations section, expand Advanced Settings.

    2. In the Storage section, on the OSS Persistence tab, click Add.

    3. Configure the OSS volume parameters.

      • Name: The name of the OSS volume.

      • Bucket: The name of the OSS bucket.

      • RAM Role: The RAM role that has permissions to access OSS.

    Mount a volume

    1. In the Container Configurations section, select a container and expand its advanced settings.

    2. Turn on the Storage switch and click Add.

      The available volumes are those you declared in the container group configuration.

      In the storage configuration row, set Volume to a declared volume, such as oss-demo, select a storage type, such as OSS Persistence, and enter a Mount Path in Container, such as /data. Optionally, specify a Sub Path, such as test, and select the Read-only checkbox.

    Note

    If you want to mount volumes to multiple containers, select more containers and repeat the preceding operations.

    Configuration example

    1. Create an elastic container instance, Instance A, and mount an OSS volume to it.

      The following example shows the parameters used to call the CreateContainerGroup operation to create Instance A. For more information, see CreateContainerGroup.

      ContainerGroupName=test-oss-a
# Declare the volume
Volume.1.Name=oss-demo
Volume.1.Type=FlexVolume
Volume.1.FlexVolume.Driver=alicloud/oss
Volume.1.FlexVolume.Options={"bucket":"test-***","url":"oss-cn-hangzhou-internal.aliyuncs.com","ramRole":"ram-***"}
# 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=oss-demo
Container.1.VolumeMount.1.MountPath=/data-a

    2. Connect to Instance A and create a file in the mount directory.

      For information about how to connect to an elastic container instance, see Connect to an ECI instance by using Workbench.

      root@test-oss-a:/# cd data-a
root@test-oss-a:/data-a# ls
root@test-oss-a:/data-a# echo "hello" >test
root@test-oss-a:/data-a# ls
test
root@test-oss-a:/data-a# cat test
hello

    3. Delete Instance A.

    4. Create another elastic container instance, Instance B, and mount the same OSS volume to it.

      ContainerGroupName=test-oss-b
# Declare the volume
Volume.1.Name=oss-demo
Volume.1.Type=FlexVolume
Volume.1.FlexVolume.Driver=alicloud/oss
Volume.1.FlexVolume.Options={"bucket":"test-***","url":"oss-cn-hangzhou-internal.aliyuncs.com","ramRole":"ram-***"}
# 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=oss-demo
Container.1.VolumeMount.1.MountPath=/data-b

    5. Connect to Instance B and check the file in the mount directory.

      Because OSS provides persistent storage, you can still access the file written by Instance A from Instance B, even after Instance A is deleted.

      root@test-oss-b:/# cd data-b
root@test-oss-b:/data-b# ls
test
root@test-oss-b:/data-b# cat test
hello