Docs

Container Registry

Image warm-up

Configuring image warm-up

Image warm-up is used to distribute images in advance to the central cache nodes or workload nodes of target VKE clusters, which reduces image pull load during concentrated releases and shortens container startup time. It applies to scenarios that need shorter pull latency, such as concentrated version releases, preparation before cluster node scale-out, and cold starts of large GPU images. You can create a warm-up policy to specify the image scope, target cluster, and trigger method. CR then automatically creates and runs warm-up tasks.

Limits

Image warm-up is supported only on Standard Edition standard instances. It is not supported on proxy cache registries.

Only CR instances that are associated with the VKE P2P add-on support this feature. For how to associate a CR instance with the P2P add-on, see p2p-accelerator.

Prerequisites

Volcengine Kubernetes Engine

P2P acceleration has been configured in VKE, and this CR instance has been associated with the P2P add-on. For details, see Configuring P2P acceleration.

A namespace has been created. For details, see CR namespaces.

An OCI artifact repository has been created. For details, see Creating OCI artifact repositories.

At least one image tag has been pushed to the created OCI artifact repository. For details, see Pushing and pulling artifacts.

Procedure

Step 1: Create a warm-up policy

Select the target region in the top navigation bar.

In the left navigation pane, Click Instance list > Standard instance. Find the target instance and click Enter instance.

In the left navigation pane, click Distribution acceleration > Image warm-up.

Click Create warm-up policy and configure the warm-up policy parameters.

Basic information

Parameter
Description
policy name
The custom name of the warm-up policy.

Warm-up configuration

Parameter	Description
Instance	By default, the name of the CR instance to which the warm-up policy belongs is displayed.
Namespace	Select the namespaces in this instance that need to be warmed up. You can select multiple namespaces.
Repository	Select the scope of OCI artifact repositories to be warmed up. The valid values are as follows: All: Synchronize all OCI artifact repositories in the specified namespace. Regular expression matching: Matches the OCI artifact repositories to be replicated by using a regular expression. For common regex matching examples, see Regular expression matching examples.
Image tag	Select the scope of image tags to be warmed up. The valid values are as follows: All: Warms up all image tags in the selected repository within the namespace. Regular expression matching: Matches image tags to be warmed up using a regular expression. For common regex matching examples, see Regular expression matching examples.
Target cluster	Select the VKE cluster to which the warmed-up images are distributed. After the warm-up task is created, CR distributes the images to the target node type specified for this cluster. tip The drop-down list shows only VKE clusters for which warm-up policies can be created in this instance. For warm-up policy requirements for VKE, see Limits and Prerequisites in this topic.
Target node type	Select the distribution scope of the image within the VKE cluster. When the warm-up task runs, CR distributes the images to the nodes specified here. The valid values are as follows: Central cache node: Images are distributed to the P2P central cache node, and workload nodes pull images from the central cache at startup. This option applies to scenarios in which images are shared across multiple clusters and nodes are frequently scaled in and out. Partial business nodes: Images are cached locally on workload nodes in advance. When pods start, they read images directly from the workload node's local storage and bypass the central cache node. If the target cluster also has a central cache node, the central cache node also keeps a copy of the cache. This option applies to scenarios with large image sizes, strict requirements on pod cold-start latency, and the need to completely avoid remote origin pulls.
Target platform	When the target image is a multi-architecture image, select the image architecture to warm up. The valid values are as follows: linux/amd64: Applies to nodes with the x86_64 architecture. linux/arm64: Applies to nodes with the ARM architecture.

Warm-up policy

Parameter	Description
Policy status	The enabled state of the warm-up policy. It is enabled by default. After the policy is disabled, no new tasks are generated, but tasks already in progress are not affected.
Trigger method	Select the trigger method for the warm-up task. The valid values are as follows: Event trigger: A warm-up task is created automatically each time an image is successfully pushed. No additional configuration is required. Scheduled trigger: Warm-up tasks are created periodically on the specified schedule. The First trigger time and Trigger frequency parameters are required. First trigger time: The time at which the first warm-up task is triggered. It must be later than the current time (accurate to the second). Trigger frequency: The frequency at which the warm-up task is triggered. A warm-up task is created at the interval specified as Trigger frequency (1 to 24 hours). Manual trigger: The policy does not create tasks automatically. In the warm-up policy list in the console, click Manual trigger in the Actions column. Each click creates one warm-up task.
Single-node timeout	The timeout duration for running warm-up on a single node. The value ranges from 1 to 1440 minutes, with a default of 10 minutes. After the timeout, the warm-up on the node is marked as failed, and the warm-up is retried based on the Retry count value.
Number of retries	The number of automatic retries after a warm-up failure on a single node. The value ranges from 1 to 10, with a default of 3.

Step 2: Trigger a warm-up task

After a warm-up policy is created, you can trigger warm-up tasks in either of the following two ways.

Automatic trigger

If Trigger method is set to Scheduled trigger or Event trigger when the policy is created, the system automatically initiates warm-up tasks when the trigger conditions are met, without any manual operation.

Manually trigger

If Trigger method is set to Manual trigger when the policy is created, manually trigger warm-up tasks in the console.

On the Distribution acceleration > Image warm-up page, in the Actions column of the target warm-up policy, click Manual trigger.

In the confirmation box, click Confirm.

Step 3: View warm-up tasks

After you open the warm-up policy details page, you can view the execution status of all warm-up tasks on the Task execution records tab.

On the Distribution acceleration > Image warm-up page, click the target policy name to enter the policy details page.

Click the Task execution records tab and view the execution status of each warm-up task in the task list.

Parameter	Description
Task ID	The ID of the warm-up task, which is automatically generated by the system. You can search for tasks by full ID in the search box.
Source policy	The name of the warm-up policy that triggered this task.
Trigger method	The trigger method for the task. The valid values are Manual trigger, Scheduled trigger, and Event trigger. Event trigger: A warm-up task is created automatically each time an image is successfully pushed. Scheduled trigger: Warm-up tasks are created periodically on the specified schedule. Manual trigger: In the warm-up policy list in the console, click Manual trigger in the Actions column. Each click creates one warm-up task.
Image	The processing results of the images involved in this task. The numbers of images that were warmed up successfully, failed, or were canceled are displayed.
Target cluster	The name of the target VKE cluster for this warm-up task.
Target node type	The type of nodes to which warm-up images are distributed. The valid values are Central cache node and Partial business nodes. Central cache node: Images are distributed to the P2P central cache node in the cluster. Workload nodes pull images from the central cache at startup, without consuming local disk space. Partial business nodes: Images are cached locally on workload nodes in advance. When pods start, they read images directly from the workload node's local storage and bypass the central cache node.
Status	The current status of the task. The valid values are as follows: Pending execution: The task has been created, has passed the pre-checks, and is waiting for resources to be scheduled. Scheduling: The system is resolving the target nodes and assigning execution batches. In progress: At least one execution batch has been dispatched to the nodes. Success: Image warm-up is complete. Failed: Pre-checks, scheduling, or execution results have met the failure conditions. You can click Retry in the Actions column to reinitiate the task. Cancelled: The task ended early because the user terminated it, the source policy was deleted, or the warm-up capability was disabled on the target cluster.
Creation time	The task creation time.
Duration	The duration of the task execution.
Action	The operations that you can perform on the task, which depend on the current task status: When the task status is Pending execution, click Terminate to cancel the task. When the task status is Failed, click Retry to reinitiate the task. The retry generates a new task record.

Click the target task ID to view the warm-up task details.

Task information

Parameter	Description
Task ID	Task ID.
Status	The current status of the task. The valid values are Pending execution, Scheduling, In progress, Success, Failed, and Cancelled.
Source policy	The name of the warm-up policy that triggered this task.
Trigger method	The trigger source of the task. The valid values are Manual trigger, Scheduled trigger, and Event trigger.
Target cluster	The name of the target VKE cluster for this warm-up task.
Target node type	The valid values are Central cache node and Partial business nodes.
Creation time	The task creation time.
Start time	The time when the task started.
End time	The time when the task execution ends (succeeded, failed, or canceled).
Duration	The elapsed time from when the task started to when it ended.
Reason	The failure reason displayed when the task fails.
Alerting	The alert messages generated during task execution.

Image execution overview

Parameter	Description
Total number of images	The total number of images involved in this warm-up task.
Completed	The number of images for which warm-up has completed, including both successes and failures.
Success	The number of images that have been warmed up.
Fail	The number of images that failed to be warmed up.
In progress	The number of images that are currently being warmed up.
Cancelled	The number of images that were canceled.

Image warm-up records

If the task as a whole fails but some images are warmed up, you can filter failed images by status in this list and use the Reason field in Task information to quickly locate pull issues for specific images.

Parameter	Description
Image/Digest	The address and digest identifier of the warmed-up image.
Image format	The format type of the image.
Target node type	The valid values are Central cache node and Partial business nodes.
Target platform	The target runtime platform of the image.
Status	The warm-up status of this image. You can filter by status.
Creation time	The creation time of this image warm-up record.
Duration	The elapsed time for warming up this image.

Last updated: 2026.10.15 19:23:05

Parameter	Description
policy name	The custom name of the warm-up policy.