When creating an image cache with the ImageCache CRD, add annotations to control networking, image registry authentication, cache optimization, and cache lifecycle. This topic lists all supported annotations with YAML examples for each scenario.
Annotations overview
The following table lists all supported annotations, grouped by purpose.
|
Annotation |
Example value |
Description |
|
Networking |
||
|
|
"vsw-bp1dktddjsg5nktv**,vsw-bp1xpiowfm5vo8o3c**" |
vSwitch IDs for multi-zone image cache creation. Separate multiple IDs with commas. Default: the vSwitch configured in eci-profile. |
|
|
|
Security group ID. Default: the security group configured in eci-profile. |
|
|
|
Resource group ID. Default: the resource group configured in eci-profile. |
|
Image registry authentication |
||
|
|
|
Container Registry Enterprise Edition instance IDs for secret-free image pulling. To pull from an instance in a different region, prefix the instance ID with the region ID: |
|
|
|
Alibaba Cloud Resource Names (ARNs) of RAM roles in the Alibaba Cloud account that owns the Elastic Container Instance (ECI) resources. Required when using a RAM role to create resources. |
|
|
|
ARNs of RAM roles in the Alibaba Cloud account that owns the Container Registry instance. Required for cross-account image pulling. |
|
|
"harbor.pre.com,192.168.XX.XX:5000,reg.test.com:80" |
Address of a self-managed image repository that uses HTTP. By default, elastic container instances pull images over HTTPS. Add this annotation so the instance uses HTTP for the specified repository. |
|
|
"harbor.pre.com,192.168.XX.XX:5000,reg.test.com:80" |
Address of a self-managed image repository that uses a self-signed certificate. Add this annotation to skip certificate verification and prevent pull failures. |
|
Cache optimization |
||
|
|
|
Enables image cache layer reuse. When creating an image cache, the system checks existing image caches and reuses any matching image layers, reducing creation time. |
|
|
|
Enables instant image cache. The system creates a temporary local snapshot, making the image cache available immediately. In the background, the system creates a standard snapshot; after it is ready, the local snapshot is removed automatically. |
|
Cache lifecycle |
||
|
|
|
Retention period in days. Expired image caches are deleted automatically. Default: blank (never expires). |
|
|
|
Image cache size in GiB. Default: 20. Valid range: 20–32768. |
|
Internet access via EIP |
||
|
|
|
ID of an existing Elastic IP Address (EIP) to associate with the temporary elastic container instance during image cache creation. The EIP is retained after the image cache is created. |
|
|
|
Automatically creates an EIP and associates it with the temporary elastic container instance. The EIP is released after the image cache is created. |
|
|
|
Bandwidth limit of the auto-created EIP, in Mbit/s. |
|
|
|
Billing method for the auto-created EIP. Valid values: |
|
|
|
Line type for the auto-created EIP. Only applicable to pay-as-you-go EIPs. Valid values: |
|
|
|
ID of the EIP bandwidth plan to associate with the auto-created EIP. |
Multi-zone image cache creation
ECI creates a temporary elastic container instance to pull and cache images. To keep cache creation succeeding even when a zone is unavailable, specify multiple vSwitches across different zones.
Note: By default, the vSwitch configured in the Kubernetes cluster or VNode is used. If the cluster or VNode already spans multiple zones, you may not need to specify vSwitches explicitly.
apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
name: imagecache-sample
annotations:
k8s.aliyun.com/vswitch-ids: "vsw-bp1dktddjsg5nktv****,vsw-bp1xpiowfm5vo8o3c****" # Multiple vSwitches for multi-zone support.
spec:
images:
- centos:latest
- busybox:latest
imageCacheSize: 25
retentionDays: 7Configure a security group and resource group
By default, the security group and resource group from eci-profile are used. Use the following annotations to override them for a specific image cache.
apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
name: imagecache-sample
annotations:
k8s.aliyun.com/security-group-id: "sg-bp1dktddjsg5nktv****" # Override the default security group.
k8s.aliyun.com/resource-group-id: "rg-aek2z3elfs4****" # Override the default resource group.
spec:
images:
- centos:latest
- busybox:latest
imageCacheSize: 25
retentionDays: 7Pull images from Container Registry without a Secret
Secret-free image pulling lets ECI pull images from Container Registry without Kubernetes Secrets. Support depends on whether the Container Registry instance is in the same Alibaba Cloud account and which edition you use.
|
Same account |
Container Registry edition |
Secret-free image pulling |
|
Yes |
Personal Edition or Enterprise Edition (default domain) |
Enabled by default. Configure a RAM role to limit the scope of instances that support secret-free pulling. |
|
Yes |
Enterprise Edition (custom domain) |
Not enabled by default. Specify the Container Registry instances explicitly using |
|
No |
Personal Edition or Enterprise Edition |
Not enabled by default. Configure a RAM role using |
For configuration details, see Pull images from a Container Registry instance without using a Secret.
Use self-managed image repositories
If a self-managed image repository uses HTTP or a self-signed certificate, image pulls fail with ErrImagePull by default. Add the appropriate annotation to prevent the failure.
HTTP repositories
By default, elastic container instances pull images over HTTPS. If your self-managed repository uses HTTP, image pulls fail with ErrImagePull. Add k8s.aliyun.com/plain-http-registry to allow HTTP for the specified repository.
apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
name: imagecache-sample
annotations:
k8s.aliyun.com/plain-http-registry: "192.168.XX.XX:5000" # Allow HTTP pulls from this repository.
spec:
images:
- 192.168.XX.XX:5000/test/nginx:latest
imagePullSecrets:
- default:secret1
- default:secret2
- kube-system:secret3
imageCacheSize: 25
retentionDays: 7Self-signed certificate repositories
If your self-managed repository uses a self-signed certificate, image pulls fail with ErrImagePull. Add k8s.aliyun.com/insecure-registry to skip certificate verification for the specified repository.
apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
name: imagecache-sample
annotations:
k8s.aliyun.com/insecure-registry: "harbor***.pre.com" # Skip certificate verification for this repository.
spec:
images:
- harbor***.pre.com/test/nginx:latest
imagePullSecrets:
- default:secret1
- default:secret2
- kube-system:secret3
imageCacheSize: 25
retentionDays: 7To pull from multiple repositories, separate their addresses with commas:harbor***.pre.com,192.168.XX.XX. If a repository address includes a port, include the port in the annotation value:192.168.XX.XX:5000.
Enable image cache layer reuse
Image cache creation time depends on image size and network conditions. With layer reuse enabled, the system checks existing image caches before creating a new one and reuses any matching layers—significantly reducing creation time for images that share common base layers.
apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
name: imagecache-sample
annotations:
k8s.aliyun.com/imc-enable-reuse: "true" # Reuse matching layers from existing image caches.
spec:
images:
- centos:latest
- busybox:latest
imageCacheSize: 25
retentionDays: 7Enable instant image cache
With instant image cache enabled, the system first creates a temporary local snapshot for the disks of the temporary elastic container instance. The image cache becomes available as soon as the local snapshot is ready—without waiting for a full standard snapshot.
After the local snapshot is created, the system creates a standard snapshot in the background. The image cache remains usable throughout this process. Once the standard snapshot is ready, the local snapshot is removed automatically and the image cache continues to work from the standard snapshot.
apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
name: imagecache-sample
annotations:
k8s.aliyun.com/imc-enable-flash: "true" # Enable instant image cache for faster availability.
spec:
images:
- centos:latest
- busybox:latest
imageCacheSize: 25
retentionDays: 7Configure cache size and retention period
By default, image caches are 20 GiB in size and never expire. Set the size and retention period using annotations or the imageCacheSize and retentionDays fields in the spec section.
apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
name: imagecache-sample
annotations:
k8s.aliyun.com/imc-retention-days: "7" # Delete the image cache after 7 days.
k8s.aliyun.com/imc-size: "25" # Set the image cache size to 25 GiB.
spec:
images:
- centos:latest
- busybox:latestConfigure internet access via an EIP
During image cache creation, the temporary elastic container instance must reach the internet to pull images. If your VPC has no NAT gateway, associate an Elastic IP Address (EIP) with the temporary instance.
Two options are available:
|
Option |
EIP lifecycle |
|
Use an existing EIP |
The EIP is retained after the image cache is created. |
|
Auto-create an EIP |
The EIP is released together with the temporary instance after the image cache is created. |
Use an existing EIP
apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
name: imagecache-sample
annotations:
k8s.aliyun.com/eip-instance-id: "eip-bp1q5n8cq4p7f6dzu****" # Associate an existing EIP.
spec:
images:
- centos:latest
- busybox:latest
imageCacheSize: 25
retentionDays: 7Auto-create an EIP
apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
name: imagecache-sample
annotations:
k8s.aliyun.com/auto-create-eip: "true" # Auto-create and associate an EIP.
k8s.aliyun.com/eip-bandwidth: "10" # Bandwidth limit in Mbit/s.
k8s.aliyun.com/eip-internet-charge-type: PayByBandwidth # Billing method: PayByBandwidth or PayByTraffic.
k8s.aliyun.com/eip-common-bandwidth-package-id: "cbwp-2zeukbj916scmj51m****" # EIP bandwidth plan ID.
spec:
images:
- centos:latest
- busybox:latest
imageCacheSize: 25
retentionDays: 7