A data cache pre-pulls data from a source — such as an OSS bucket, a NAS file system, or a model repository — and stores it as a snapshot. Elastic container instances in the same region can mount the cache directly at startup, eliminating per-container data fetching and reducing startup time.
This topic covers how to create, query, update, copy, and delete a data cache.
Prerequisites
Before you begin, ensure that you have:
A virtual private cloud (VPC), a vSwitch, and a security group in the target region
(If pulling data over the internet) An elastic IP address (EIP), or a vSwitch with SNAT entries configured
Data cache states
| State | Meaning |
|---|---|
Available | The data cache is ready to mount. |
UpdateFailed | The last update attempt failed. The cache can still be updated again. |
Limitations
Review the following constraints before creating a data cache:
A data cache is region-specific and cannot be shared across regions. To use a cache in a different region, copy it first.
Updating a data cache is only supported via API. The console does not support this operation.
Each data cache is backed by a snapshot. Storage fees apply as long as the cache exists. To avoid ongoing costs, set a retention period or delete the cache when it is no longer needed.
Create a data cache
Creation methods
| Method | How |
|---|---|
| API | Call the CreateDataCache operation. |
| Console | In the Elastic Container Instance console, click Data Cache in the left navigation pane. On the Data Cache page, click Create Data Cache, configure the parameters, and click OK. |
Parameters
Basic properties
| API parameter | Console label | Description |
|---|---|---|
RegionId | Region | The region where the data cache is created. |
Bucket | Cache bucket | The bucket used to group cached data and avoid path conflicts. Default: default. The eci-system bucket is reserved and cannot be used. |
Path | Cache directory | The storage path for the cached data within the bucket. |
Name | Cache name | The name of the data cache. |
Size | Cache size | The cache size in GiB. Default: 20. Set this based on the actual data volume. |
RetentionDays | Retention period (days) | The number of days before the cache is automatically deleted. If not set, the cache does not expire and snapshot storage fees continue to accrue. |
Data source
| API parameter | Console label | Description |
|---|---|---|
DataSource.Type | Type | The type of data source. |
DataSource.Options | Parameters | A JSON object containing source-specific parameters. |
The following table lists the supported data source types and their options.
When calling the API directly (not via an SDK), prefix each parameter name under DataSource.Options with its character count. For example, url (3 characters) becomes #3#url, and repoId (6 characters) becomes #6#repoId. SDKs handle this automatically — no prefix is required.
| Type | Data source | Options |
|---|---|---|
URL | A URL to download from | url: the download URL. accessToken: an access token for private data. |
HuggingFace or ModelScope | A model or dataset from Hugging Face or ModelScope | repoSource: one of ModelScope/Model, ModelScope/DataSet, HuggingFace/Model, or HuggingFace/DataSet. repoId: the model or dataset ID. revision: the version (default: main or master). accessToken: an access token for private data. |
NAS | A File Storage NAS file system | server: the mount target. path: the subdirectory path. For extreme NAS file systems, prefix the path with /share (for example, /share/path). vers: the NFS protocol version. Use NFS v3. Extreme NAS only supports NFS v3. options: mount options. Recommended: nolock,tcp,noresvport. |
OSS | An Object Storage Service (OSS) bucket | bucket: the OSS bucket name. url: the OSS endpoint. path: the subdirectory path relative to the bucket root. Default: /. otherOpts: custom mount options in the format -o option1 -o option2 (for example, -o max_stat_cache_size=0 -o allow_other). ramRole: the RAM role for access. akId: the AccessKey ID for access. akSecret: the AccessKey secret for access. |
SNAPSHOT | An existing snapshot | snapshotId: the snapshot ID. |
To use a RAM role for OSS access, create a RAM role with Alibaba Cloud Service as the trusted entity, Normal Service Role as the role type, and Elastic Compute Service as the trusted service. Attach the AliyunOSSFullAccess policy to the role. For details, see Create a RAM role for a trusted Alibaba Cloud service and Grant permissions to a RAM role.
Network parameters
If the data source is on the internet and the vSwitch does not have SNAT entries configured, associate an EIP with the cache creation instance.
| API parameter | Console label | Description |
|---|---|---|
EipInstanceId | Use existing | Associates an existing EIP with the instance. |
Parameters under EipCreateParam | Auto create | Creates a new EIP and associates it automatically. |
Configuration examples
The following examples show how to create data caches of different types using the API.
URL
Pull data from a URL:
{
"RegionId": "cn-beijing",
"SecurityGroupId": "sg-2ze63v3jtm8e6syi****",
"VSwitchId": "vsw-2ze94pjtfuj9vaymf****",
"Bucket": "test",
"Path": "/demo/url",
"Name": "test-url-1",
"DataSource": {
"Type": "URL",
"Options": {
"#3#url": "https://www.example.com"
}
},
"RetentionDays": 1
}Pull a model from Hugging Face:
{
"RegionId": "cn-beijing",
"SecurityGroupId": "sg-2ze63v3jtm8e6syi****",
"VSwitchId": "vsw-2ze94pjtfuj9vaymf****",
"Bucket": "test",
"Path": "/demo/url",
"Name": "test-url-2",
"DataSource": {
"Type": "URL",
"Options": {
"#10#repoSource": "HuggingFace/Model",
"#6#repoId": "stabilityai/stable-diffusion-2-1"
}
},
"RetentionDays": 1
}NAS
{
"RegionId": "cn-beijing",
"SecurityGroupId": "sg-2ze63v3jtm8e6syi****",
"VSwitchId": "vsw-2ze94pjtfuj9vaymf****",
"Bucket": "test",
"Path": "/demo/nas",
"Name": "test-nas",
"DataSource": {
"Type": "NAS",
"Options": {
"#6#server": "126c24****-tw***.cn-beijing.nas.aliyuncs.com",
"#4#path": "/",
"#4#vers": "3",
"#7#options": "nolock,tcp,noresvport"
}
},
"RetentionDays": 1
}OSS
{
"RegionId": "cn-beijing",
"SecurityGroupId": "sg-2ze63v3jtm8e6syi****",
"VSwitchId": "vsw-2ze94pjtfuj9vaymf****",
"Bucket": "test",
"Path": "/demo/oss",
"Name": "test-oss",
"DataSource": {
"Type": "OSS",
"Options": {
"#6#bucket": "test-***",
"#3#url": "oss-cn-beijing-internal.aliyuncs.com",
"#4#path": "/test",
"#9#otherOpts": "-o max_stat_cache_size=0 -o allow_other",
"#7#ramRole": "<your RAM role name>"
}
},
"RetentionDays": 1,
"SourceIp": "2401:b180:1000:3:a4ba:83d6:a4ba:83d6"
}Snapshot
{
"RegionId": "cn-beijing",
"SecurityGroupId": "sg-2ze63v3jtm8e6syi****",
"VSwitchId": "vsw-2ze94pjtfuj9vaymf****",
"Bucket": "test",
"Path": "/demo/snapshot",
"Name": "test-snapshot",
"DataSource": {
"Type": "SNAPSHOT",
"Options": {
"#10#snapshotId": "s-2zehb6jegdehec19****"
}
},
"RetentionDays": 1,
"Size": 40
}Manage a data cache
Query a data cache
After creating a data cache, check its status to confirm it is ready. A cache in the Available state can be mounted by elastic container instances.
| Method | How |
|---|---|
| API | Call the DescribeDataCaches operation. |
| Console | On the Data Cache page, view all caches in the selected region. Click a cache ID to view its details, including status, bucket, and storage path. |
Update a data cache
A data cache in the Available or UpdateFailed state can be updated. Updatable fields include the bucket, data source, retention period, and size.
| Method | How |
|---|---|
| API | Call the UpdateDataCache operation. |
| Console | Not supported. |
Copy a data cache to another region
A data cache is region-specific. To use it in a different region, copy it to the target region first.
| Method | How |
|---|---|
| API | Call the CopyDataCache operation. |
| Console | On the Data Cache page, find the cache and click Copy in the Actions column. |
Delete a data cache
Each data cache is backed by a snapshot, which incurs storage charges. Delete caches that are no longer needed — especially if no retention period is set — to avoid ongoing costs.
| Method | How |
|---|---|
| API | Call the DeleteDataCache operation. |
| Console | On the Data Cache page, find the cache and click Delete in the Actions column. |