Create an image cache.

Usage instructions

This is an asynchronous API. When this API returns a success message, it will return the ID of the image cache, and the image cache will enter the {Creating, [Progressing]} state, until it is successfully created and enters the {Ready, [Ok]} state. You can call the ListImageCaches API to obtain the current status of the image cache and check whether the image cache has been created.

Before you create an image cache, you need to prepare the required container images. You can use images from Volcano Engine CR as well as images from third-party container registries. For instructions on uploading images to CR, see Pushing and pulling images.

Each Volcano Engine root user, including sub-users, can have up to 20 image caches, excluding image caches that are being deleted (status: [Deleting,*]). If this upper limit is reached, new image caches cannot be created. You can delete image caches that are no longer used, or submit a ticket to apply for a quota increase.

Request description

VKE has deployed services in multiple regions globally to provide a stable and low-latency access experience. You can refer to the Service addresses topic and select the most suitable access point for your business region.

Request method: POST

Request URL: https://vke.cn-beijing.volcengineapi.com?Action=CreateImageCache&Version=2022-05-12

Request parameters

The following table lists the API request parameters. You must also provide public parameters when calling this API. For details, see Public parameters.

Parameter	Type	Required	Sample value	Description
Action	String	Yes	CreateImageCache	The API name. The name of the current API is CreateImageCache.
Version	String	Yes	2022-05-12	The API version. The current version of the API is 2022-05-12.
ImageCacheName	String	Yes	test-imc	The image cache name. The image cache name must be unique in the same region. It can contain uppercase and lowercase letters, digits, and hyphens (-) and is 1 to 64 characters in length.
SubnetIds	Array of String	Yes	["subnet-3rf6vwbgkg****"]	The ID of the subnet to which the image cache belongs. You can call a VPC API to obtain the ID of the target subnet. tip You can enter up to five subnet IDs at a time.
SecurityGroupIds	Array of String	Yes	["sg-2byy13cnsczy****"]	The IDs of the security groups to which the network of the image cache belongs. You can call the DescribeSecurityGroups API of VPC to obtain the security group IDs. tip You can enter up to five security group IDs at a time.
Images	Array of String	Yes	["cr-cn-beijing.volces.com/vke****/nginx:latest"]	The list of container images that are required to create the image cache.
ImageCacheSize	Integer	No	50	The image cache capacity. Unit: GiB. Valid values: 40 to 500. Default value: 40.
ImageRegistryCredentials	Array of ImageRegistryCredentials	No	-	The access credentials of CR.
AutoPrewarmConfig	Object of AutoPrewarmConfig	No	-	The warm-up policy configurations of the EBS snapshots that correspond to the image cache.
RetentionDays	Integer	No	15	The retention duration of the image cache. After expiration, the image cache will be cleared. Unit: days. Valid values: 1 to 365. The value must be a positive integer. Warning If you do not specify this parameter in the request parameters, the image cache will expire after 15 days.
RegistryHostnameResolvNameservers	Array of String	No	["10.xx.xx.xx", "10.xx.xx.xx"]	The IP addresses of DNS servers used for resolving hostnames. You can enter 0 to 3 IP addresses. Each IP address must be a valid IPv4 address.
BaseImageCacheId	String	No	imc-3uqroqkx0i3j****	Specify an existing image cache and enable incremental image cache creation. After you specify an existing image cache, the newly created image cache will reuse the image layer of the specified image cache, which accelerates the cache creation. Warning The image cache must be in the Ready state. You can call the ListImageCaches API to obtain the current status of the image cache.

Parameter	Type	Required	Sample value	Description
Action	String	Yes	CreateImageCache	The API name. The name of the current API is CreateImageCache.
Version	String	Yes	2022-05-12	The API version. The current version of the API is 2022-05-12.
ImageCacheName	String	Yes	test-imc	The image cache name. The image cache name must be unique in the same region. It can contain uppercase and lowercase letters, digits, and hyphens (-) and is 1 to 64 characters in length.
SubnetIds	Array of String	Yes	["subnet-3rf6vwbgkg****"]	The ID of the subnet to which the image cache belongs. You can call a VPC API to obtain the ID of the target subnet. tip You can enter up to five subnet IDs at a time.
SecurityGroupIds	Array of String	Yes	["sg-2byy13cnsczy****"]	The IDs of the security groups to which the network of the image cache belongs. You can call the DescribeSecurityGroups API of VPC to obtain the security group IDs. tip You can enter up to five security group IDs at a time.
Images	Array of String	Yes	["cr-cn-beijing.volces.com/vke****/nginx:latest"]	The list of container images that are required to create the image cache.
ImageCacheSize	Integer	No	50	The image cache capacity. Unit: GiB. Valid values: 40 to 500. Default value: 40.
ImageRegistryCredentials	Array of ImageRegistryCredentials	No	-	The access credentials of CR.
AutoPrewarmConfig	Object of AutoPrewarmConfig	No	-	The warm-up policy configurations of the EBS snapshots that correspond to the image cache.
RetentionDays	Integer	No	15	The retention duration of the image cache. After expiration, the image cache will be cleared. Unit: days. Valid values: 1 to 365. The value must be a positive integer. Warning If you do not specify this parameter in the request parameters, the image cache will expire after 15 days.
RegistryHostnameResolvNameservers	Array of String	No	["10.xx.xx.xx", "10.xx.xx.xx"]	The IP addresses of DNS servers used for resolving hostnames. You can enter 0 to 3 IP addresses. Each IP address must be a valid IPv4 address.
BaseImageCacheId	String	No	imc-3uqroqkx0i3j****	Specify an existing image cache and enable incremental image cache creation. After you specify an existing image cache, the newly created image cache will reuse the image layer of the specified image cache, which accelerates the cache creation. Warning The image cache must be in the Ready state. You can call the ListImageCaches API to obtain the current status of the image cache.

ImageRegistryCredentials

Parameters	Type	Required	Sample value	Description
Server	String	Yes	cr-cn-beijing.volces.com	The domain name of the CR instance that does not start with http:// or https://. Obtain the domain name of the CR instance by using the CR console or by calling the ListDomains API of CR.
UserName	String	Yes	user_**@21000**	The username for accessing the CR instance. Obtain the username for accessing the CR instance by using the CR console or by calling the GetUser API.
Password	String	Yes	dGhpcyBpcyBh********	The password that corresponds to the username of the CR instance. Warning You need to Base64-encode the password before passing it in. For more information about Base64 encoding, see FAQ. You can also obtain a temporary access key to access the CR instance. For detailed operations, see GetAuthorizationToken.

AutoPrewarmConfig

Parameters	Type	Required	Sample value	Description
ZoneIds	Array of String	No	["cn-beijing-b"]	The IDs of the availability zones for snapshots to be warmed up. tip If you do not specify this parameter, the availability zones that correspond to the subnets specified during the creation of the image cache are used by default.
PrewarmRetentionDays	Integer	No	90	The warm-up retention duration for the EBS snapshots that correspond to the image cache. Unit: days. Valid values: 1 to 180. Default value: 90.

Sample requests

Response parameters

The following table contains the response parameters of this API. See Response results for details about public response parameters.

Parameter	Type	Sample value	Description
ImageCacheId	String	imc-3uqroqkx0i3jabcdefgs	The ID of the image cache.

Sample responses

Error code

The error codes for this API are listed in the table below. Refer to the Public error codes topic for public error codes.

HTTP status code	Error code	Error message	Description
400	LimitExceeded.ImageCacheSize	You have reached the limit of the size of image cache that you can create.	The size of the specified image cache exceeds the upper limit. Check the valid values of the ImageCacheSize parameter.
400	VpcMismatch.{{Parameter}}	The specified {{resourceType}} {{resourceId}} and {{resourceType}} {{resourceId}} are not in the same vpc.	The specified subnet, security group, and other resources do not belong to the same VPC. Make sure that they are deployed in the same VPC.
400	OutOfStorage.ImageCacheSize	The size of the specified image cache is too small.	The size of the specified image cache is too small. Check the valid values of the ImageCacheSize parameter.
400	Conflict.Name	The specified name conflicts with existing {{resourceType}}.	An image cache with the same name already exists in the specified region. Update the image cache name and try again later.
400	NotFound.BaseImageCacheId	The specified imageCache {{BaseImageCacheId}} not found	The specified base image cache for incremental creation of the image cache does not exist. Check the ID of the existing image cache and try again later.
400	OperationDenied.ImageCacheStatus	The action has been denied due to wrong source image cache status {{Status}}.	The current status of the specified existing image cache does not support this operation. Check whether the status of the existing image cache specified by the BaseImageCacheId parameter is Ready and try again later.

Volcengine Kubernetes Engine