Create an image cache by using the CreateImageCache API - Elastic Container Instance - Alibaba Cloud - Elastic Container Instance

Creates an image cache to accelerate image pulling and reduce startup time for subsequent Elastic Container Instance (ECI) instance creation.

Operation description

Precautions

Creating an image cache incurs resource fees. Learn about the billing information in advance. For more information, see Image cache billing.
Before creating an image cache, evaluate the total size of the images to be cached. If the total image size exceeds the configured cache size, the creation will fail.
When creating an image cache, the system automatically creates an ECI instance and a PL1 ESSD cloud disk for intermediate image automatic creation. Do not delete the ECI instance or cloud disk during the creation process. Otherwise, the image automatic creation will fail.
Creating an image cache generates a corresponding snapshot. Do not delete the snapshot. Otherwise, the image cache will become invalid.
If you use an SDK, the required version is Java 1.0.10 or later, or Python 1.0.7 or later.

Recommendations

For Container Registry Enterprise Edition images that use custom domain names, specify the Container Registry instance (by setting AcrRegistryInfo parameters) to configure password-free access. When setting AcrRegistryInfo parameters, you must set AcrRegistryInfo.N.InstanceId.
If the image cache will be used to create a large number of ECI instances (more than 1,000) in batches, set StandardCopyCount and FlashCopyCount to enable the multi-copy snapshot feature. Multi-copy snapshots are billed based on incremental data. Because the data of the snapshot copies created at the same time is identical, the multi-copy snapshot feature does not incur additional fees.

Note

When you call CreateImageCache to create an image cache, the system automatically creates a service-linked role named AliyunServiceRoleForECI to access related cloud services such as ECS and VPC. For more information, see Elastic Container Instance service-linked role.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

eci:CreateImageCache

create

*ImageCache

acs:eci:{#regionId}:{#accountId}:imagecache/*

eci:tag

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID.	cn-hangzhou
RegionId	string	Yes	The zone.	cn-hangzhou-g
ZoneId	string	No	The security group ID.	sg-uf66jeqopgqa9hdn****
SecurityGroupId	string	No	The vSwitch ID. You can specify multiple vSwitch IDs (up to 10 at a time), separated by commas (,). Example: `vsw-*,vsw-*`.	vsw-uf6h3rbwbm90urjwa****
VSwitchId	string	No	The name of the image cache.	testcache
ImageCacheName	string	Yes	The Elastic IP Address (EIP). If you need to pull images from the Internet, make sure that the ECI instance can access the Internet. You can configure an EIP or a NAT gateway to enable public network access.	eip-2zedsm5mfl3uhdj2d****
EipInstanceId	string	No	The resource group ID.	rg-aekzh43v*****
ResourceGroupId	string	No	The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but you must make sure that the token is unique among different requests. The token can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.	123e4567-xxx-xxx-xxxx-42665544xxxx
ClientToken	string	No	The size of the image cache. Default value: 20 GiB.	20
ImageCacheSize	integer	No	The retention period of the image cache. The image cache is deleted after it expires. By default, the image cache never expires. Note Image caches that fail to be created are retained for only one day.	7
RetentionDays	integer	No	Specifies whether to enable image cache reuse. If this feature is enabled, a newly created image cache can reuse image layers from existing image caches, which accelerates image cache creation. Valid values: true: Enable image cache reuse. false: Disable image cache reuse. Default value: false.	true
AutoMatchImageCache	boolean	No	The image repository information.	true
ImageRegistryCredential	array<object>	No	The container images used to create the image cache.	registry-vpc.cn-hangzhou.aliyuncs.com/eci_open/nginx:1.15.10-perl
	object	No	The container images used to create the image cache.	registry-vpc.cn-hangzhou.aliyuncs.com/eci_open/nginx:1.15.10-perl
Password	string	No	The password for the image repository.	password
Server	string	No	The address of the image repository. Do not include the `http://` or `https://` prefix.	registry-vpc.cn-hangzhou.aliyuncs.com
UserName	string	No	The username for the image repository.	username
Image	array	Yes	The tag information of the image cache. You can specify up to 20 tags.	registry-vpc.cn-hangzhou.aliyuncs.com/eci_open/nginx:1.15.10-perl
	string	No	The tag information of the image cache. You can specify up to 20 tags.	registry-vpc.cn-hangzhou.aliyuncs.com/eci_open/nginx:1.15.10-perl
Tag	array<object>	No	Specifies whether to enable the instant image cache feature, which accelerates image cache creation. Valid values: true: Enable the instant image cache feature. false: Disable the instant image cache feature. Default value: false.	true
	object	No	The tags of the image cache. You can specify up to 20 tags.
Key	string	No	The key of the image cache tag.	imc
Value	string	No	The value of the image cache tag.	test
Flash	boolean	No	The Container Registry instance information. For more information, see Pull images from Container Registry without using a password.	true
AcrRegistryInfo	array<object>	No	The annotations. This parameter is not available for public use.	hide
	object	No	The information about the ACR instance.
Domain	array	No	The domain names of the ACR Enterprise instance. By default, all domain names of the instance are specified. You can specify one or more domain names. Separate multiple domain names with commas (,).	test****-registry.cn-beijing.cr.aliyuncs.com
	string	No	The domain names of the ACR Enterprise instance. By default, all domain names of the instance are specified. You can specify one or more domain names. Separate multiple domain names with commas (,).	test****-registry.cn-beijing.cr.aliyuncs.com
InstanceName	string	No	The name of the ACR Enterprise instance.	test****
InstanceId	string	No	The ID of the ACR Enterprise instance.	cri-nwj395hgf6f3****
RegionId	string	No	The region where the ACR Enterprise instance resides.	cn-beijing
ArnService	string	No	The Alibaba Cloud Resource Name (ARN) of the RAM role that belongs to the account of the resource, such as an ECI instance.	acs:ram::1609982529******:role/role-assume
ArnUser	string	No	The ARN of the RAM role that belongs to the account of the ACR instance.	acs:ram::1298452580******:role/role-acr
Annotations	string	No	The address of the self-pull image repository. When you create an image cache by using images from a self-pull image repository that uses the HTTP protocol, configure this parameter so that ECI pulls images over HTTP, preventing image pull failures caused by protocol mismatch.	"harbor*.pre.com,192.168.XX.XX:5000,reg*.test.com:80"
PlainHttpRegistry	string	No	The address of the self-managed image repository. When you create an image cache by using images from a self-managed image repository that uses a self-signed certificate, configure this parameter to skip certificate authentication, preventing image pull failures caused by certificate authentication failure.	"harbor*.pre.com,192.168.XX.XX:5000,reg*.test.com:80"
InsecureRegistry	string	No	The number of regular snapshot copies. By default, one image cache corresponds to one snapshot. If the image cache will be used to create multiple ECI instances in batches, configure this parameter to enable the multi-copy snapshot feature. We recommend that you add one snapshot copy for every 1,000 ECI instances. Note When the instant image cache feature is disabled (Flash is set to false), only regular snapshots are generated during image cache creation.	7
StandardCopyCount	integer	No	The number of local snapshot copies. By default, one image cache corresponds to one snapshot. If the image cache will be used to create multiple ECI instances in batches, configure this parameter to enable the multi-copy snapshot feature. We recommend that you add one snapshot copy for every 1,000 ECI instances. Note When the instant image cache feature is enabled (Flash is set to true), local snapshots are created first during image cache creation. After the local snapshots are created, regular snapshots start to be created. After the regular snapshots are created, the local snapshots are automatically deleted.	7
FlashCopyCount	integer	No	The elimination strategy of the image cache. The default value is empty, which indicates that the image cache is always retained. You can set this parameter to LRU, which indicates that the image cache can be automatically deleted. When the number of image caches reaches the quota limit, the system automatically deletes the least recently used image caches whose EliminationStrategy is set to LRU.	LRU
EliminationStrategy	string	No	The operating system of the container images. Valid values: Linux (default) Windows Note Windows is in invitational preview. To use it, submit a ticket.	Linux
OsType	string	No	The operating system of the container image. Valid values: Linux (default) Windows Note Windows is in invitational preview. To use this feature, submit a ticket.	Linux

Response elements

Element	Type	Description	Example
	object
RequestId	string	The request ID, which is a unique identifier.	0E234675-3465-4CC3-9D0F-9A864BC391DD
ImageCacheId	string	The image cache ID.	imc-2zebxkiifuyzzlhl****
ContainerGroupId	string	The instance ID of the ECI instance used for intermediate image cache creation.	eci-2zebxkiifuyzzlhl****

Examples

Success response

JSON format

{
  "RequestId": "0E234675-3465-4CC3-9D0F-9A864BC391DD",
  "ImageCacheId": "imc-2zebxkiifuyzzlhl****",
  "ContainerGroupId": "eci-2zebxkiifuyzzlhl****"
}

Error codes

HTTP status code	Error code	Error message	Description
400	Account.Arrearage	Your account has an outstanding payment.	Your account has an outstanding payment.
400	DryRunOperation	Request validation has been passed with DryRun flag set.	Request validation has been passed with DryRun flag set.
400	InvalidParameter.CPU.Memory	The specified cpu and memory are not allowed
400	IncorrectStatus	%s	The specified instance status is invalid.
400	ServiceNotEnabled	%s	The service on which this request depends has not been activated. Please activate and try again.
400	DiskVolume.NotSupport	The disk volume is not supported.	Disk volume does not support your structure. If you want to enable this function, contact us.
400	RamRole.NotSupport	The RAM role is not supported.	The RAM role is not supported.
400	ImageCache.IncorrectStatus	%s	The image cache is not in the correct state.
400	ImageCacheNotSupport	Image cache is not available for all users. If you want to enable this function, contact us.	Container image cache is currently not available to all users. Submit a ticket if you need to use the feature.
400	EipAddressPoolIpNotEnough	The ip address of specified PublicIpAddressPool is not enough.	The specified EIP public address pool does not have sufficient address resources.
400	OperationConflict	The request was denied. It conflicts with a previous request.
403	OperationDenied.VswZoneMisMatch	The specified VSwitchId is not in the specified Zone.
403	QuotaExceeded	%s quota exceeded.
403	Zone.NotOnSale	The specified zone is not available for purchase.	The zone in which you want to create the instance is no longer available for purchase. Use a different zone, or the vSwitch of the specified VPC cannot be used in this zone.
403	Forbidden.RiskControl	This operation has been identified as an abnormal operation and cannot be processed.	This operation has been identified as abnormal and cannot be processed.
403	Forbidden.SubUser	The specified action is not available for you.
403	Forbidden.OnlyForInvitedTest	Eci create action is only open to invited users during public beta.
403	OperationDenied.SecurityGroupMisMatch	The specified VSwitchId and SecurityGroupId are not in the same VPC.
403	InvalidVSwitchId.IpNotEnough	The specified VSwitch does not have enough IP addresses.
403	Forbidden.UserBussinessStatus	This operation is not allowed, because you have overdue bills. Pay the overdue bill and try again.	The operation is forbidden because the account has an overdue payment. Top up your account and try again.
403	Forbidden.UserNotRealNameAuthentication	This operation is not allowed, because you have not passed the real-name verification.	The operation is forbidden because the user has not completed real-name verification.
403	InvalidUser.PassRoleForbidden	The RAM user is not authorized to assume a RAM role.	The RAM user is not authorized to assume a RAM role.
403	OperationDenied.NoStock	Sales of this resource are temporarily suspended in the specified zone. We recommend that you use the multi-zone creation function to avoid the risk of insufficient resource. For more information, see https://www.alibabacloud.com/help/document_detail/157290.html
403	NoPermission	The RAM role AliyunECIContainerGroupRole does not belong to eci.aliyuncs.com. Please check and try again.
403	SecurityRisk.3DVerification	We have detected a security risk with your default credit or debit card. Please proceed with verification via the link in your email.	A security risk has been detected on your default credit or debit card. Verify your card by using the link in the email.
403	CreateServiceLinkedRole.Denied	Please make sure the account has ram:CreateServiceLinkedRole permission.	Please make sure the account has ram:CreateServiceLinkedRole permission.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.