Updated on 2025-09-23 GMT+08:00

Using an Image Cache

In a CCE Autopilot cluster, you can create a workload using an image cache in either of the following ways:

  • The optimal images will be selected from all available image caches you have created.
  • You need to specify an available image cache.

For details, see Procedure.

Prerequisites

A CCE Autopilot cluster of v1.28.8, v1.31.4, or later is available.

Constraints

  • When an image cache is used, an EVS disk is automatically attached to each pod. Each EVS disk has the same size as that of the image cache and will be created and released together with the pod. Container image information is automatically stored in each EVS disk.
  • When creating a workload, you can select only one image cache. If the images in the image cache cannot fully match the workload, unmatched images still need to be downloaded from the original image repository.
  • Image caches are mainly used to accelerate image download. When using an image cache, ensure that the network connectivity between the workload and image repository is normal and the image download credentials are correct.
  • If an image cache expires after a workload is created using the image cache, the created workload is not affected. However, if you need to perform operations on the workload, such as upgrading or scaling the workload, the image cache cannot be used. In this case, you need to download the images again.

Billing

Operation Phase

Billed Item

Billing Description

Reference

Using an image cache

Pod

When an image cache is used, an EVS disk is automatically attached to each pod. Each EVS disk has the same size as that of the image cache and will be created and released together with the pod.

For details about pod price, see Billing Items of CCE Autopilot Clusters.

Procedure

There are two ways to use an image cache in the CCE Autopilot cluster: console and kubectl.

  1. Log in to the CCE console and click the cluster name to access the cluster console.
  2. In the navigation pane, choose Workloads. On the right of the page, select the required workload type.
  3. Click Create Workload in the upper right corner of the page. In the Container Settings area, configure the image cache parameters. For details about other parameters, see Creating a Workload. You can select a reference document based on the workload type.

    There are three options for Image Cache. For details, see Figure 1 and Table 1. In this example, select Specify and use the cache image created in Creating an Image Cache.

    Figure 1 Specifying an image cache
    Table 1 Image cache parameters

    Parameter

    Example Value

    Description

    Do not use

    -

    No image cache will be used. The images will be downloaded based on the configuration in Container Setting.

    Auto allocate

    -

    The optimal images will be selected from all available image caches based on:
    • How much the images match the image caches: The images in the most matched images will be used.
    • Time when the image caches were created: The images in the latest image cache will be used.

    You can enter the name of the image to be used for Image Name (Container Information > Basic Info > Image Name). The images are matched based on the preceding rules. If no images are matched in the image cache, the image cache is no longer used. In this case, the images in the SWR image repository and open-source images are matched in sequence based on the specified image name. If no images are matched, a message is returned indicating that images fail to be pulled.

    Specify

    autopilot-test

    Select an existing image cache. The image cache must be in the Available state. To create an image cache, click Create Image Cache. For details about the parameters, see Creating an Image Cache.

    NOTE:

    After the image cache is specified, you need to enter the address of the image to be used in the image cache (Container Information > Basic Info > Image Name). In addition, you are advised not to select Always for Pull Policy (Container Settings > Basic Info > Pull Policy) to prevent repeatedly pulling images from the original image repository.

    To obtain image path, move the cursor to the specified image cache and view Image in the displayed tip.

  4. Configure other parameters and click Create Workload. If the workload status changes to Running, the workload is created.

    You can click the workload name in the workload list to go to the workload details page. Switch to the Containers tab to view the image cache.

The following uses an Nginx workload as an example to describe how to use an image cache by using kubectl.

  1. Run the kubectl command to connect to the cluster. For details, see Connecting to a Cluster Using kubectl.
  2. Create a YAML file for creating a workload. In this example, the file name is imagecache.yaml. You can change it as needed.

    Only image cache parameters are described here. For details, see Table 2. For details about other parameters, see Creating a Deployment.
    vim imagecache.yaml

    Example file content:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: nginx    # Workload name
    spec:
      replicas: 1     # Number of pods
      selector:
        matchLabels:  
          app: nginx  
      template:
        metadata:
          labels:     
            app: nginx
          annotations: 
            imagecache.cce.io/specified-name: "autopilot-test"    #Specifies the image cache.
            imagecache.cce.io/auto-match: "true"    # Automatically matches the image cache.
        spec:
          containers:
          - image: swr.cn-east-3.myhuaweicloud.com/test/nginx:latest  # Enter the image path to be used.
            imagePullPolicy: IfNotPresent # You are advised to set ImagePullPolicy to IfNotPresent to avoid repeatedly pulling images from the original image repository.
            name: nginx
          imagePullSecrets:
          - name: default-secret

    Press Esc to exit editing mode and enter :wq to save the file.

    Table 2 Key parameters

    Parameter

    Mandatory

    Type

    Description

    imagecache.cce.io/specified-name

    No

    String

    Specifies the image cache. Enter the name of an available image cache. After the image cache is specified, the image information in the containers parameter must be the same as that in the image cache.

    When this parameter is used, you need to enter the image path to be used in the containers.image parameter. If the specified image cache does not exist or the required images are not found in the image cache, the image cache is no longer used. The cluster will download the images based on the image information in the containers parameter.

    imagecache.cce.io/auto-match

    No

    String

    Specifies whether to enable automatic image cache matching. The options are as follows:

    • true: This option is enabled.
    • false: This option is disabled by default.

    After this option is enabled, the optimal images will be selected from all available image caches based on:

    • How much the images match the image caches: The images in the most matched images will be used.
    • Time when the image caches were created: The images in the latest image cache will be used.

    If no images are matched, no image caches will be used.

    The two parameters indicate the two methods of using an image cache. You only need to set one of them. If both parameters are specified, imagecache.cce.io/specified-name is used preferentially. If neither of the two parameters is specified, no image caches are used by default.

  3. Run the following command to create the workload:

    kubectl create -f imagecache.yaml

    If information similar to the following is displayed, the workload is being created:

    deployment.apps/nginx created

  4. Run the following command to check the workload status:

    kubectl get deployment

    If the value of READY is 1/1, the pod created for the workload is available. This means the workload has been created.

    NAME     READY   UP-TO-DATE   AVAILABLE   AGE
    nginx    1/1     1            1           4m59s