Pull an image from a self-managed image repository

How it works

ECI evaluates annotations on the pod or ImageCache resource at creation time to determine how to connect to the image repository:

• k8s.aliyun.com/plain-http-registry — use HTTP instead of HTTPS for the specified registry addresses.

• k8s.aliyun.com/insecure-registry — skip TLS certificate verification for the specified registry addresses.

Multiple registries: Separate addresses with commas. If the registry address includes a port, include the port in the annotation value. For example, if your image is at 192.168.XX.XX:5000/nginx:latest, set the value to 192.168.XX.XX:5000.

Annotation placement

• Add annotations to metadata in the pod spec. For a Deployment, this is spec.template.metadata, not the top-level metadata.

• Annotations take effect only at pod creation time. Adding or modifying annotations on an existing pod has no effect.

Pull images from an HTTP registry

Use k8s.aliyun.com/plain-http-registry when the registry does not use TLS. Without this annotation, ECI attempts to connect over HTTPS and fails.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  replicas: 4
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      name: nginx-test
      annotations:
        k8s.aliyun.com/plain-http-registry: "192.168.XX.XX:5000"  # Registry address — ECI pulls over HTTP instead of HTTPS
      labels:
        app: nginx
        alibabacloud.com/eci: "true"
    spec:
      containers:
      - name: nginx
        image: 192.168.XX.XX:5000/test/nginx:latest

apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
  name: imagecache-sample
  annotations:
    k8s.aliyun.com/plain-http-registry: "192.168.XX.XX:5000"  # Registry address — ECI pulls over HTTP instead of HTTPS
spec:
  images:
  - 192.168.XX.XX:5000/test/nginx:latest
  imagePullSecrets:
  - default:secret1
  - default:secret2
  - kube-system:secret3
  imageCacheSize: 25
  retentionDays: 7

Pull images from a registry with a self-signed certificate

Use k8s.aliyun.com/insecure-registry when the registry uses HTTPS but the certificate is self-signed. Without this annotation, ECI rejects the certificate and the image pull fails.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  replicas: 4
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      name: nginx-test
      annotations:
        k8s.aliyun.com/insecure-registry: "harbor***.pre.com"  # Registry address — ECI skips TLS certificate verification
      labels:
        app: nginx
        alibabacloud.com/eci: "true"
    spec:
      containers:
      - name: nginx
        image: harbor***.pre.com/test/nginx:latest

apiVersion: eci.alibabacloud.com/v1
kind: ImageCache
metadata:
  name: imagecache-sample
  annotations:
    k8s.aliyun.com/insecure-registry: "harbor***.pre.com"  # Registry address — ECI skips TLS certificate verification
spec:
  images:
  - harbor***.pre.com/test/nginx:latest
  imagePullSecrets:
  - default:secret1
  - default:secret2
  - kube-system:secret3
  imageCacheSize: 25
  retentionDays: 7

Troubleshooting

If image pulls still fail after adding the annotation, check the following:

Annotation placement: Confirm the annotation is in spec.template.metadata.annotations for a Deployment, not in the top-level metadata. Run kubectl get pod <pod-name> -o yaml and verify the annotation appears under the pod's metadata.annotations.

Annotation applied at creation: If the pod already existed when you added the annotation, delete the pod and let the Deployment recreate it. Annotations only take effect on new pods.

Registry address format: Check that the annotation value exactly matches the registry hostname and port used in the image reference. For example, if your image is 192.168.XX.XX:5000/test/nginx:latest, the annotation value must be 192.168.XX.XX:5000, not 192.168.XX.XX.

Wrong annotation for the scenario: If the registry uses HTTP, use k8s.aliyun.com/plain-http-registry. If it uses HTTPS with a self-signed certificate, use k8s.aliyun.com/insecure-registry. Using the wrong annotation does not resolve the failure.

Network connectivity: Verify that ECI can reach the registry. Run kubectl describe pod <pod-name> and check the Events section for additional details on the failure reason.