CreateImageCache
Creates or reuses an image cache for ACR Enterprise Edition images in a workspace, and returns the cache status upon acceptance.
Operation description
Prepares or reuses an ACR Enterprise Edition image cache for custom code or image agents for subsequent deployment and startup.
Request parameters
regionId, workspaceId, and clientToken are passed as query parameters. The region must match the entry endpoint and the workspace.
The JSON request body provides acrInstanceId, namespace, repository, and tag. For repository, specify only the repository name without repeating the namespace. The source repository must have pull authorization for the workspace resource role. You can obtain the authorization URL by calling GetWorkspaceAcrRamAuthorizeUrl.
Transfer network
Both accessInternet and accessVpc must be provided, and at least one of them must be set to true. The server validates these parameters based on the network conditions of the workspace. These parameters control the source reading and transfer for the current operation and do not modify the runtime network of the agent.
Acceptance and readiness
A successful response returns the current cache snapshot. PENDING indicates that the cache is being prepared, READY indicates that the cache is ready, and FAILED indicates a failure. For failures, check the error field. Save the imageId and call GetImageCache to query subsequent results. If the image digest has not been parsed, digest may be empty.
Currently, clientToken is only validated to ensure it is not empty. It does not guarantee deduplication by this identifier or recovery of the original acceptance result. If the result is not confirmed, query the existing cache first.
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
agentcore:CreateImageCache |
create |
*Workspace
|
None | None |
Request syntax
POST /image-caches HTTP/1.1
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| regionId |
string |
Yes |
The product entry region, passed as a query parameter. It must match the selected region endpoint and the workspace region. |
cn-hangzhou |
| workspaceId |
string |
Yes |
The workspace ID. |
ws-example |
| clientToken |
string |
Yes |
The non-empty request identifier passed as a query parameter. The current implementation does not guarantee deduplication by this identifier or recovery of the original acceptance result. |
550e8400-e29b-41d4-a716-446655440000 |
| body |
object |
Yes |
The request body for creating an image cache. |
|
| acrInstanceId |
string |
Yes |
The ID of the source ACR Enterprise instance. |
cri-example |
| namespace |
string |
Yes |
The namespace of the source ACR. |
team |
| repository |
string |
Yes |
The name of the repository under the namespace. Do not include the namespace in the repository name. |
app |
| tag |
string |
Yes |
The selected tag of the source image. |
v1 |
| accessInternet |
boolean |
Yes |
Specifies whether to allow the use of the public network for the current source reading and transfer. At least one of this parameter and accessVpc must be set to true. The server validates the access conditions of the current workspace. |
false |
| accessVpc |
boolean |
Yes |
Specifies whether to allow the use of a VPC for the current source reading and transfer. At least one of this parameter and accessInternet must be set to true. The server resolves the trusted network of the current workspace and does not modify the runtime network of the agent. |
true |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
The response for creating an image cache. |
||
| requestId |
string |
The request ID, which is used for troubleshooting. |
req-example |
| message |
string |
The response message. |
success |
| httpStatusCode |
integer |
The HTTP status code. |
200 |
| code |
string |
The business response code. |
SUCCESS |
| success |
boolean |
Indicates whether the request is successful. This does not mean that the cache creation is complete. |
true |
| data |
object |
The result of creating the image cache. |
|
| imageId |
string |
The ID of the image cache. |
img-example |
| workspaceId |
string |
The workspace ID. |
ws-example |
| acrInstanceId |
string |
The ID of the source ACR instance. |
cri-example |
| registry |
string |
The domain name of the source image. |
example-registry.cn-hangzhou.cr.aliyuncs.com |
| repository |
string |
The path of the source image repository. |
team/app |
| tag |
string |
The tag of the source image. |
v1 |
| digest |
string |
The current content digest. |
sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa |
| status |
string |
The image cache status. Valid values:
|
READY |
| cacheSizeBytes |
integer |
The size of the cache in bytes. |
1073741824 |
| createdAt |
string |
The time when the resource was created. The time is in RFC 3339 format. The Z at the end of the example indicates the UTC time zone. |
2026-10-10T00:00:00Z |
| agentCount |
integer |
The number of agents that use the cache. |
0 |
| canDelete |
boolean |
Indicates whether deletion is allowed. |
false |
| deleteBlockReason |
string |
The reason why deletion is blocked. Valid values:
|
INSTANCES_RELEASING |
| error |
object |
The reason for the cache failure. |
|
| code |
string |
The error code for the creation failure. |
ACSCacheBuildFailed |
| message |
string |
The description of the creation failure. |
The image cache creation failed. Please try again |
Examples
Success response
JSON format
{
"requestId": "req-example",
"message": "success",
"httpStatusCode": 200,
"code": "SUCCESS",
"success": true,
"data": {
"imageId": "img-example",
"workspaceId": "ws-example",
"acrInstanceId": "cri-example",
"registry": "example-registry.cn-hangzhou.cr.aliyuncs.com",
"repository": "team/app",
"tag": "v1",
"digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "READY",
"cacheSizeBytes": 1073741824,
"createdAt": "2026-10-10T00:00:00Z",
"agentCount": 0,
"canDelete": false,
"deleteBlockReason": "INSTANCES_RELEASING",
"error": {
"code": "ACSCacheBuildFailed",
"message": "The image cache creation failed. Please try again"
}
}
}
Error codes
|
HTTP status code |
Error code |
Error message |
Description |
|---|---|---|---|
| 400 | InvalidArgument | The specified request parameter is invalid. | |
| 400 | AcrEditionUnsupported | The source ACR instance edition is not supported. | |
| 400 | AcrAccountUnsupported | The source ACR account is not supported. | |
| 400 | AcrRegionUnsupported | The source ACR region is not supported. | |
| 403 | Forbidden | The caller is not allowed to perform this operation. | |
| 403 | AcrRamUnauthorized | Source image authorization is required for image caching. | |
| 404 | NotFound | The specified source resource does not exist. | |
| 503 | ImageCacheUnavailable | No image cache execution resources are available in the requested cache region. | |
| 503 | AcrAuthorizationServiceUnavailable | The source ACR authorization service is unavailable. | |
| 409 | ImageCacheVersionConflict | The source tag is already registered with another digest. Select a new tag. | |
| 409 | ImageCacheRegionMismatch | The registered cache region is incompatible with the requested region. | |
| 409 | ImageCacheTargetChanged | The current execution configuration is incompatible with the registered cache target. | |
| 409 | ImageCacheNetworkUnavailable | No configured source transfer network supports the requested access modes. | |
| 409 | ImageCacheDeleting | The image cache is being deleted. | |
| 409 | SubmissionPending | The submission result is not confirmed. Query the current cache status before submitting again. | |
| 409 | AcrRoleConflict | The Workspace resource role configuration conflicts with the requested source. | |
| 409 | AcrPrerequisiteNotReady | The Workspace ACR prerequisites are not ready. | |
| 409 | WorkspaceDeleting | The Workspace is being deleted. | |
| 409 | AcrCapacityUnsupported | The source ACR capacity is not supported. | |
| 409 | WorkspaceNotReady | The Workspace is not ready for cache creation or retry. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.