文档中心

容器服务

镜像缓存

CreateImageCache - 创建镜像缓存

CreateImageCache - 创建镜像缓存

创建一个镜像缓存。

使用说明

此接口为异步接口，当此接口返回成功时，会返回镜像缓存的 ID 信息，此时镜像缓存将进入{Creating, [Progressing]}状态，直到创建执行成功，进入{Ready, [Ok]}状态。请调用 ListImageCaches 接口获取该镜像缓存当前的状态，查看镜像缓存是否创建成功。

创建镜像缓存前，需要准备所需的容器镜像。支持使用火山引擎镜像仓库（CR）中的镜像，也支持使用第三方镜像仓库中的镜像。CR 中上传镜像的操作，请参见推送和拉取镜像。

除了正在删除中的镜像缓存（状态为[Deleting,*]），每个火山引擎账号（含子用户）最多支持存在 20 个镜像缓存，超过后无法创建新的镜像缓存。您可以删除无用的镜像缓存，或提交工单申请提升配额。

请求说明

VKE 已在全球多个地域部署服务，旨在为您提供更稳定、低延迟的访问体验。您可以通过查阅服务地址文档，根据业务所在地域，选择最合适的接入点。

请求方式：POST

请求地址：https://vke.cn-beijing.volcengineapi.com?Action=CreateImageCache&Version=2022-05-12

请求参数

调用该 API 时的请求参数如下，除此之外还需传入公共请求参数。公共请求参数说明，请参见公共参数。

参数	类型	是否必选	示例值	描述
Action	String	是	CreateImageCache	接口名称。当前 API 的名称为 CreateImageCache。
Version	String	是	2022-05-12	接口版本。当前 API 的版本为 2022-05-12。
ImageCacheName	String	是	test-imc	镜像缓存名称。同一个地域内，镜像缓存名称必须唯一。支持大小写英文字母、数字、短划线（-），长度限制为 1～64 个字符。
SubnetIds	Array of String	是	["subnet-3rf6vwbgkg****"]	镜像缓存实例所属的子网 ID。可以调用私有网络 API 获取目标子网 ID。说明单次最多填写 5 个子网 ID。
SecurityGroupIds	Array of String	是	["sg-2byy13cnsczy****"]	镜像缓存网络所在安全组 ID。可以调用私有网络的 DescribeSecurityGroups 接口，获取安全组 ID。说明单次最多填写 5 个安全组 ID。
Images	Array of String	是	["cr-cn-beijing.volces.com/vke****/nginx:latest"]	制作镜像缓存所需要的容器镜像列表。
ImageCacheSize	Integer	否	50	镜像缓存的大小。单位：GiB。取值范围：40~500。默认值：40。
ImageRegistryCredentials	Array of ImageRegistryCredentials	否	-	镜像仓库（CR）的访问凭证信息。
AutoPrewarmConfig	Object of AutoPrewarmConfig	否	-	镜像缓存对应的弹性块存储（EBS）快照预热策略配置。
RetentionDays	Integer	否	15	镜像缓存保留时间，过期后镜像缓存会被清理。单位：天取值范围：1~365（正整数）注意请求参数中不传入该参数时，镜像缓存 15 天后过期。
RegistryHostnameResolvNameservers	Array of String	否	["10.xx.xx.xx", "10.xx.xx.xx"]	用于解析主机名的 DNS 服务器 IP 地址。支持传入 0~3 个 IP 地址。每个地址必须为合法的 IPv4 地址。
BaseImageCacheId	String	否	imc-3uqroqkx0i3j****	指定已有的镜像缓存并开启镜像缓存增量制作。指定后，新创建的镜像缓存将复用所指定镜像缓存的镜像层，加快新镜像缓存的创建速度。注意镜像缓存必须处于 Ready 状态。可以调用 ListImageCaches接口，获取镜像缓存当前状态。

ImageRegistryCredentials

参数	类型	是否必选	示例值	描述
Server	String	是	cr-cn-beijing.volces.com	不带http://或https://前缀的镜像仓库域名。通过镜像仓库控制台或调用镜像仓库的 ListDomains接口，获取镜像仓库域名。
UserName	String	是	user_**@21000**	访问镜像仓库实例的用户名。通过镜像仓库控制台或调用镜像仓库的 GetUser接口，获取访问镜像仓库实例的用户名。
Password	String	是	dGhpcyBpcyBh********	镜像仓库实例用户名对应的密码。注意需要对密码进行 Base 64 编码后传入。Base 64 编码相关注意事项，请参见 FAQ。您也可以获取临时访问密钥，访问镜像仓库实例。详细操作，请参见 GetAuthorizationToken。

AutoPrewarmConfig

参数	类型	是否必选	示例值	描述
ZoneIds	Array of String	否	["cn-beijing-b"]	需要预热的快照可用区。说明不传入参数值时，默认用创建镜像缓存时指定的子网所对应的可用区。
PrewarmRetentionDays	Integer	否	90	镜像缓存对应 EBS 快照的预热保留时长。单位：天取值范围：1~180 默认值：90

请求示例

返回参数

本接口返回参数如下表所示，公共返回参数请参见返回结果。

参数	类型	示例值	描述
ImageCacheId	String	imc-3uqroqkx0i3jabcdefgs	镜像缓存 ID。

返回示例

错误码

本接口错误码如下表所示，公共错误码请参见公共错误码。

HTTP 状态码	错误码	错误信息	说明
400	LimitExceeded.ImageCacheSize	You have reached the limit of the size of image cache that you can create.	指定的镜像缓存盘容量超过所支持的最大值。请确认 ImageCacheSize参数要求的取值范围。
400	VpcMismatch.{{Parameter}}	The specified {{resourceType}} {{resourceId}} and {{resourceType}} {{resourceId}} are not in the same vpc.	指定的子网、安全组等不同属于一个私有网络（VPC），请确保其处于同一个 VPC 内。
400	OutOfStorage.ImageCacheSize	The size of the specified image cache is too small.	指定的镜像缓存盘容量过小。请确认 ImageCacheSize参数要求的取值范围。
400	Conflict.Name	The specified name conflicts with existing {{resourceType}}.	指定的地域内已经存在同名的镜像缓存。请更新镜像缓存名称后重试。
400	NotFound.BaseImageCacheId	The specified imageCache {{BaseImageCacheId}} not found	指定的用于镜像缓存增量制作的基础镜像缓存不存在。请确认已有镜像缓存 ID 并重试。
400	OperationDenied.ImageCacheStatus	The action has been denied due to wrong source image cache status {{Status}}.	指定的已有镜像缓存当前状态不支持该操作。请确认 BaseImageCacheId 参数指定的已有镜像缓存状态是否处于 Ready状态并重试。

最近更新时间：2026.01.14 15:53:17

这个页面对您有帮助吗？

有用

有用

无用

无用