All Products
Search
Document Center

Annotations supported by ImageCaches

Last Updated: May 19, 2022

If you want to accelerate the creation of pods in a Kubernetes cluster, you can use the image cache feature in the manner of ImageCache CustomResourceDefinition (CRD). When you create an ImageCache, you can add annotations based on your business requirements. This topic describes the annotations that are supported by ImageCaches. This topic also provides examples on how to configure the annotations.

Annotations supported by ImageCaches

The following table describes the annotations that are supported by ImageCaches.

Annotation

Example

Description

k8s.aliyun.com/vswitch-ids

"vsw-bp1dktddjsg5nktv****,vsw-bp1xpiowfm5vo8o3c****"

Specifies the IDs of vSwitches. You can specify multiple vSwitches for multiple zones. If you do not specify this parameter, the ID of the vSwitch configured in eci-profile is used.

k8s.aliyun.com/security-group-id

"sg-bp1dktddjsg5nktv****"

Specifies the ID of the security group. If you do not specify this parameter, the ID of the security group configured in eci-profile is used.

k8s.aliyun.com/resource-group-id

"rg-aek2z3elfs4****"

Specifies the ID of the resource group. If you do not specify this parameter, the ID of the resource group configured in the eci-profile is used.

k8s.aliyun.com/acr-instance-ids

"cri-j36zhodptmyq****"

Specifies the IDs of Alibaba Cloud Container Registry Enterprise Edition instances. These instances are used to pull images without the need to use passwords.

You can specify Container Registry Enterprise Edition instances that reside in regions different from the region of the pod. To do this, you must prefix the region ID of the Container Registry Enterprise Edition instance to the ID of the Container Registry Enterprise Edition instance. Example: "cn-beijng:cri-j36zhodptmyq****".

k8s.aliyun.com/plain-http-registry

"harbor***.pre.com,192.168.XX.XX:5000,reg***.test.com:80"

Specifies the domain name or IP address of the self-managed image repository.

When you create an elastic container instance by using an image in a self-managed image repository that uses the HTTP protocol, you must add this annotation. This way, Elastic Container Instance uses the HTTPS protocol to pull the image. This can prevent the image from failing to pull due to different protocols.

k8s.aliyun.com/insecure-registry

"harbor***.pre.com,192.168.XX.XX:5000,reg***.test.com:80"

Specifies the domain name or IP address of the self-managed image repository.

When you create an elastic container instance by using an image in a self-managed image repository that uses a self-signed certificate, you must add this annotation to skip the certificate authentication. This can prevent the image from failing to pull due to certificate authentication failures.

k8s.aliyun.com/imc-enable-reuse

"true"

Specifies whether to enable the image cache reuse feature. If you enable this feature and the image cache that you want to create and an existing image cache contain duplicate image layers, the system reuses the duplicate image layers to create the new image cache. This accelerates the creation of the image cache.

k8s.aliyun.com/imc-enable-flash

"true"

Specifies whether to enable the instant image cache feature. If you enable this feature, the system creates a temporary local snapshot. This reduces the time required to create the image cache. You are charged for the instant availability of the local snapshot.

k8s.aliyun.com/imc-retention-days

"7"

Specifies the retention period of the image cache. Unit: days. Expired image caches are automatically cleared. This annotation is left empty by default, which indicates that the ImageCache never expires.

k8s.aliyun.com/imc-size

"25"

Specifies the size of the image cache. Unit: GiB. Default value: 20. Valid values: 20 to 32768.

k8s.aliyun.com/eip-instance-id

"eip-bp1q5n8cq4p7f6dzu****"

Specifies the ID of the elastic IP address (EIP) that is associated with the elastic container instance. If no NAT gateway is configured, you can associate an existing EIP with the elastic container instance to pull images over the Internet.

k8s.aliyun.com/auto-create-eip

"true"

Specifies whether to automatically create an EIP and associate the EIP with the elastic container instance. If no NAT gateway is configured, you can set this annotation to true. This allows the system to create an EIP and associate the EIP with the elastic container instance to pull images over the Internet.

k8s.aliyun.com/eip-bandwidth

"5"

Specifies the bandwidth limit for the EIP when the system creates an EIP.

k8s.aliyun.com/eip-internet-charge-type

PayByBandwidth

Specifies the billing method for network usage of the EIP when the system creates an EIP. Valid values:

  • PayByBandwidth

  • PayByTraffic

k8s.aliyun.com/eip-isp

BGP

Specifies the line type of the EIP when the system creates an EIP. This annotation is suitable only for pay-as-you-go EIPs. Valid values:

  • BPG: BGP (Multi-ISP) line

  • BGP_PRO: BGP (Multi-ISP) Pro line

k8s.aliyun.com/eip-common-bandwidth-package-id

"cbwp-2zeukbj916scmj51m****"

Specifies the ID of the EIP bandwidth plan.

Create an ImageCache by using the multi-zone feature

When you create an ImageCache, the system creates a temporary elastic container instance. To ensure the ImageCache can be created, you can specify multiple vSwitches that reside in different zones.

Note

If you do not specify vSwitches, the vSwitch configured in eci-profile is used. If multiple zones are configured in eci-profile, you do not need to specify vSwitches.

apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
  name: imagecache-sample
  annotations:
    k8s.aliyun.com/vswitch-ids: "vsw-bp1dktddjsg5nktv****,vsw-bp1xpiowfm5vo8o3c****" # Specifies multiple vSwitches.
spec:
  images:
  - centos:latest
  - busybox:latest
  imagePullSecrets:
  - default:secret1
  - default:secret2
  - kube-system:secret3
  imageCacheSize:
   25
  retentionDays:
   7

Configure a security group and resource group

By default, the security group and resource group that are configured in eci-profile are used when you create an ImageCache. You can configure a security group and resource group based on your business requirements.

apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
  name: imagecache-sample
  annotations:
    k8s.aliyun.com/security-group-id: "sg-bp1dktddjsg5nktv****" # Specifies a security group
    k8s.aliyun.com/resource-group-id: "rg-aek2z3elfs4****"  # Specifies a resource group.
spec:
  images:
  - centos:latest
  - busybox:latest
  imagePullSecrets:
  - default:secret1
  - default:secret2
  - kube-system:secret3
  imageCacheSize:
   25
  retentionDays:
   7

Pull Container Registry images without the need to use passwords

Container Registry is a secure platform that allows you to efficiently manage and distribute cloud-native artifacts such as container images and Helm charts that meet the standards of Open Container Initiative (OCI). Container Registry integrates with Alibaba Cloud Container Service for Kubernetes (ACK) to provide end-to-end acceleration capabilities, including acceleration of distribution of large images at scale and image building based on multiple code sources. For more information about Container Registry, see What is Container Registry?

When you create an ImageCache, you can configure a Container Registry Enterprise Edition instance to pull images from the instance without the need to use passwords.

Note

Container Registry Enterprise Edition instances can be used across regions. Therefore, you can specify a Container Registry Enterprise Edition instance that resides in a region different from the region of the ImageCache. To do this, you must prefix the region ID of the Container Registry Enterprise Edition instance to the ID of the Container Registry Enterprise Edition instance. Example: k8s.aliyun.com/acr-instance-ids: "cn-beijing:cri-j36zhodptmyq****".

apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
  name: imagecache-sample
  annotations:
    k8s.aliyun.com/acr-instance-ids: "cri-j36zhodptmyq****" # Specifies the ID of the Container Registry Enterprise Edition instance.
spec:
  images:
  - centos:latest
  - busybox:latest
  imagePullSecrets:
  - default:secret1
  - default:secret2
  - kube-system:secret3
  imageCacheSize:
   25
  retentionDays:
   7

Use self-managed image repositories

If a self-managed image repository uses the HTTP protocol or a self-signed certificate when you use an image in the image repository to create an ImageCache, you must configure annotations to prevent the image from failing to pull.

  • The self-managed image repository uses the HTTP protocol.

    By default, elastic container instances pull images over the HTTPS protocol. When you create an ImageCache, you must add the k8s.aliyun.com/plain-http-registry annotation. This allows the elastic container instance to interact with the image repository over the HTTP protocol.

    apiVersion: eci.alibabacloud.com/v1
    kind: ImageCache
    metadata:
      name: imagecache-sample
      annotations:
        k8s.aliyun.com/plain-http-registry: "192.168.XX.XX:5000"  # Specifies the domain name or IP address of the self-managed image repository to pull an image over the HTTP protocol.
    spec:
      images:
      - 192.168.XX.XX:5000/test/nginx:latest
    
      imagePullSecrets:
      - default:secret1
      - default:secret2
      - kube-system:secret3
      imageCacheSize:
       25
      retentionDays:
       7
  • The self-managed image repository uses a self-signed certificate.

    If the self-managed image repository uses a self-issued certificate, the certificate authentication fails when the system attempts to pull an image from the image repository. You must add the k8s.aliyun.com/insecure-registry annotation to skip certificate authentication.

    apiVersion: eci.alibabacloud.com/v1
    kind: ImageCache
    metadata:
      name: imagecache-sample
      annotations:
        k8s.aliyun.com/insecure-registry: "harbor***.pre.com"  # Specifies the domain name or IP address of the self-managed image repository to skip certificate authentication when the system pulls an image from the image repository.
    spec:
      images:
      - harbor***.pre.com/test/nginx:latest
    
      imagePullSecrets:
      - default:secret1
      - default:secret2
      - kube-system:secret3
      imageCacheSize:
       25
      retentionDays:
       7
Note

  • If you want to pull images of multiple containers from different image repositories, you can specify multiple domain names and IP addresses of image repositories. Separate multiple domain names and IP addresses with commas (,). Example: harbor***.pre.com,192.168.XX.XX.

  • If the domain name or IP address of the image repository contains a port number, you must specify the domain name or IP address with its port number. For example, if the IP address of the image repository is 192.168.XX.XX:5000/nginx:latest, set the value of the annotation to 192.168.XX.XX:5000.

Enable the image cache reuse feature

The time required to create an ImageCache depends on factors such as the image size and network conditions. You can enable the image cache reuse feature to reduce the time required to create an ImageCache.

After you enable the image cache reuse feature, the system matches existing ImageCaches when you create an ImageCache. If an existing ImageCache contains an image layer that you want to use, the system reuses the image layer to reduce the time required to create the ImageCache.

apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
  name: imagecache-sample
  annotations:
    k8s.aliyun.com/imc-enable-reuse: "true" # Enables the image cache reuse feature.
spec:
  images:
  - centos:latest
  - busybox:latest
  imagePullSecrets:
  - default:secret1
  - default:secret2
  - kube-system:secret3
  imageCacheSize:
   25
  retentionDays:
   7

Enable the instant image cache feature

The time required to create an ImageCache depends on factors such as the image size and network conditions. You can enable the instant image cache feature to reduce the time required to create an ImageCache.

After you enable the instant image cache feature, the system creates a temporary local snapshot for you to create the ImageCache. After the local snapshot is created, the ImageCache is available for use.

Note

  • You are charged based on the size of the local snapshot and the number of times that the local snapshot is used. The fee for a local snapshot is calculated by using the following formula: The fee = Unit price per time × 1 time + Unit price of an instant snapshot × Snapshot size × Usage duration.

  • After the local snapshot is created, the system begins to create a regular snapshot. After the regular snapshot is created, the system deletes the local snapshot.

apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
  name: imagecache-sample
  annotations:
    k8s.aliyun.com/imc-enable-flash: "true" # Enables the instant image cache feature.
spec:
  images:
  - centos:latest
  - busybox:latest
  imagePullSecrets:
  - default:secret1
  - default:secret2
  - kube-system:secret3
  imageCacheSize:
   25
  retentionDays:
   7

Configure the size and retention period of the ImageCache

By default, an ImageCache is 20 GiB in size and is permanently retained after it is created. If you want to customize the size and retention period of the ImageCache, you can specify the imageCacheSize and retentionDays parameters in the spec section, or add annotations.

apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
  name: imagecache-sample
  annotations:
    k8s.aliyun.com/imc-enable-reuse: "7" # Specifies the retention period of the image cache.
    k8s.aliyun.com/imc-size: "25" # Specifies the size of the image cache.
spec:
  images:
  - centos:latest
  - busybox:latest
  imagePullSecrets:
  - default:secret1
  - default:secret2
  - kube-system:secret3

Configure an EIP to pull images over the Internet

EIPs are public IP addresses that you can purchase and use as independent resources. When an EIP is associated with a cloud resource, the cloud resource can use the EIP to connect to the Internet. For more information about EIPs, see What is an EIP?

When you create an ImageCache, make sure that you are connected to the Internet before you pull images over the Internet. You can be connected to the Internet by configuring a NAT gateway or configuring an EIP. If your virtual private cloud (VPC) is not associated with a NAT gateway, you can configure an EIP to pull images over the Internet. You can use one of the following methods to configure an EIP.

Note

When you create an ImageCache, the system creates a temporary elastic container instance and associates the EIP with the elastic container instance. If you use an existing EIP, the EIP is retained after the ImageCache is created. If the system creates an EIP and associates the EIP with the temporary elastic container instance, the EIP and the temporary elastic container instance are released after the ImageCache is created.

  • Associate an existing EIP with the temporary elastic container instance

    apiVersion: eci.alibabacloud.com/v1
    kind: ImageCache
    metadata:
      name: imagecache-sample
      annotations:
        k8s.aliyun.com/eip-instance-id: "eip-bp1q5n8cq4p7f6dzu****" # Associates an existing EIP with the temporary elastic container instance.
    spec:
      images:
      - centos:latest
      - busybox:latest
      imagePullSecrets:
      - default:secret1
      - default:secret2
      - kube-system:secret3
      imageCacheSize:
       25
      retentionDays:
       7
  • Automatically create an EIP and associate the EIP with the temporary elastic container instance

    apiVersion: eci.alibabacloud.com/v1
    kind: ImageCache
    metadata:
      name: imagecache-sample
      annotations:
        k8s.aliyun.com/auto-create-eip: "true" # Automatically creates an EIP and associates the EIP with the temporary elastic container instance.
        k8s.aliyun.com/eip-bandwidth: "10" # Specifies the bandwidth limit of the EIP.
        k8s.aliyun.com/eip-internet-charge-type: PayByBandwidth # Specifies the billing method for network usage of the EIP.
        k8s.aliyun.com/eip-common-bandwidth-package-id: "cbwp-2zeukbj916scmj51m****" # Specifies the ID of the EIP bandwidth plan.
    spec:
      images:
      - centos:latest
      - busybox:latest
      imagePullSecrets:
      - default:secret1
      - default:secret2
      - kube-system:secret3
      imageCacheSize:
       25
      retentionDays:
       7