Docs

Volcengine Kubernetes Engine

VCI Image Cache

Creating VCIs by using automatically created image caches

During container creation, image pulling often takes a long time. To address this problem, you can use the automatic image caching solution to accelerate VCI creation.

Usage limits

The following limits apply when you use the automatic image caching solution to accelerate VCI creation.

Limitation item	Restriction
Image cache disks (cloud disks)	By default, only 40 GiB of storage space is provided. If the required cache capacity for the target container image exceeds 40 GiB, you need to specify the required storage space separately. Otherwise, image cache creation may fail.
Image cache snapshots	The validity period of an image cache is 15 days. After the cache expires, creating a cloud disk by using the image takes longer or may fail. tip We recommend that you manually create a cloud disk based on the image cache in advance and trigger the cloud disk to warm up and cache snapshot data. Cache warm-up must be performed in the target region and availability zone where the image cache will be used.
Image cache capabilities	Automatic image caching is disabled by default and needs to be enabled by using a particular annotation. If you use an automatically created image cache to create a VCI, the system disk capacity of the VCI must be greater than or equal to the size of the matched or used image cache. APIs for automatic image caching are not yet provided. To use automatic image caching, you need to create a small number of pods in advance to trigger and complete image cache creation. You can use it to create a large number of business pods after the cache enters the [Ready.Ok] state. Unused automatically created image caches are retained for a maximum of 15 days. If an image cache is used during VCI creation, its expiration time is refreshed to "matching time + 15 days". If it remains unused for 15 consecutive days, it is automatically cleaned up. Each Volcano Engine root user, including IAM 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 needed or request a quota increase in the Quota Center. For details, see Viewing and applying for quotas. VCI supports the instant availability capability of EBS to shorten the time from image cache creation to availability. This capability is an independent beta feature. To use it, submit an additional application. tip If you apply for a trial of the VCI image cache feature for the first time and simultaneously need the instant availability feature of EBS, request access to these features in the same application.

Procedure

Step 1: Prepare a container image

Prepare the container image to be used for creating a VCI. You can use images from Volcano Engine CR as well as images from third-party container registries.

This topic uses an image from CR as an example. To upload an image to CR, see Pushing and pulling images.

Step 2: (Optional) Automatically cache and warm up the image

Before creating a VCI, confirm whether the container image to be used is a new image. If it is a new image, you need to add the image to the cache and warm it up in advance.

tip

A new image refers to a container image whose image name, image tag, image layer data, and other attributes are different from those of existing images.

We recommend first creating a small number of pod instances to trigger and complete creation of an image cache. The following example demonstrates how to create a Deployment that contains one pod instance and is deployed by using VCI. For details, see Creating general-purpose instances by specifying container vCPUs and memory.

Using the console

Using YAML

Create a VCI-related cluster.

Create a Deployment. When you create the Deployment, configure some parameters as described below.

a. Basic information: Select Volcengine Container Instance for the Computing power type parameter.

b. Container configuration: Select the prepared new image.

c. Advanced settings: In the Instance annotation field, add the following annotation: vci.vke.volcengine.com/enable-auto-create-imc:"true".

warning

By default, VCI provides only 40 GiB of storage space for an image cache. If a larger cache capacity is required for the target container image, you need to add an additional annotation in this step: vci.vke.volcengine.com/auto-imc-disk-size: "specific capacity size (GiB)" to specify the required image cache disk size. For example, if 80 GiB is needed, also add the vci.vke.volcengine.com/auto-imc-disk-size: "80" annotation.

Click Confirm to create the VCI Deployment.

Step 3: Confirm image cache availability

Use the OpenAPI interface ListImageCaches to query all image cache files that belong to the current Volcano Engine root user.

warning

An automatically created image cache can be properly matched and used to create VCIs only when its status is [Ready.Ok].

Step 4: Accelerate VCI creation with automatic image caching

After confirming that the target image cache is available, you can use it to create a large number of VCI pods. You can use the following methods:

tip

To ensure that a VCI created using an image cache can function normally, manually specify the system disk size by adding a pod annotation when creating the VCI. This practice helps ensure enough space for storing the image cache and deploying VCI system components. For more information, see Pod annotations.

The annotation key is vci.vke.volcengine.com/desired-system-storage, and the annotation value should be set according to the following principles:

Automatic image cache matching: Image size × 2 to image size × 2.5. For example, if the image size selected for VCI creation is 20 GiB, you need to specify a system volume size of 40 GiB to 50 GiB.

Manually specified image cache: Image cache size + 20 GiB. For example, if your image cache size is 60 GiB, you need to specify a system volume size of 80 GiB.

The capability of manually specifying the system disk volume is in beta. To use this capability, submit an application.

Automatically matching image caches

Manually matching image caches

When creating a VCI, select an image that has already been automatically cached. For details, see Creating instances.

The system automatically matches the optimal image cache based on the matching strategy to create VCIs. For the strategy of automatically matching image caches, see Using image caches.

tip

If you have not performed Step 2, you need to add the vci.vke.volcengine.com/enable-auto-create-imc:"true" annotation to the spec·template·metadata of the VCI to enable automatic image caching.