Docs

Container Registry

Image push and pull

Pulling Docker Hub images via proxy cache registry domain name

A proxy cache instance leverages the proxy cache's caching capability to enable nearby access, effectively improving cross-border image pull efficiency. This topic describes how to pull official and unofficial third-party Docker Hub images through a proxy cache registry domain name.

warning

To pull unofficial Docker Hub images through a proxy cache registry, enable image pull authentication for the registry. Then, configure the username and password required to access the images.

This topic applies to images running in VKE clusters. For instructions on pulling images through a proxy cache registry for VCI clusters using the VPC-CNI container network model, see Creating instances and configuring proxy cache repositories.

Comparison of pull methods

Image types	Official image identifier	Pull command format	Example
Docker official image	A Docker official image with the Docker Official Image identifier.	docker pull [proxy-cache-registry-domain]/library/[image-name]:[tag]	docker pull ****.cr.volces.com/library/stable-alpine3.23-perl
Unofficial Docker image	An unofficial Docker image without the Docker Official Image identifier.	docker pull [proxy-cache-registry-domain]/[username]/[image-name]:[tag]	docker pull ****.cr.volces.com/grafana/grafana:main-ubuntu

Prerequisites

A VKE cluster has been created. For details, see Creating clusters.

Optional: When using a Standard Edition proxy cache registry, obtain the VPC information of the VKE cluster. You can view the VPC information on the cluster overview page.

Procedure

Step 1: Create a proxy cache registry

Log in to the CR console and create a proxy cache registry. This step describes only the parameters relevant to this scenario. For other parameters, see Creating proxy cache registries.

Parameter	Description
Proxy cache	Select the proxy cache registry type. Type: Select Docker. Image pull authentication: Enable this option when pulling unofficial Docker images. Enter the username and password to log in to the target Docker Hub account.

On the proxy cache registry overview page, obtain the access domain name.

(Optional) When using a Standard Edition proxy cache registry, add the VKE cluster's VPC on the Access control > VPC page. This ensures network connectivity between the proxy cache registry and the cluster. For instructions, see Connecting to the VPC of the current account.

tip

A Micro Edition proxy cache registry uses the private network in the same region by default. No additional configuration is required.

Step 2: Pull the image

Use the access domain name to pull the image to the proxy cache registry. The following command provides an example:

Results

After the image is pulled successfully, you can view it on the image details page of the proxy cache registry.

Deploy an application

You can reference images in the proxy cache registry in multiple ways to deploy applications.

Method 1: Use the proxy cache registry domain name

Use the access domain name obtained in Step 1 to pull and use the image. Sample code:

apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-demo
labels:
app: nginx-demo
spec:
replicas: 1
selector:
matchLabels:
app: nginx-demo
template:
metadata:
labels:
app: nginx-demo
spec:
containers:
- name: nginx
# Replace the original image address nginx:stable-alpine3.23-perl
# with the proxy cache registry access domain name + /library/image-name:tag.
# Replace ****.cr.volces.com with the actual access domain name obtained in Step 1.
image: ****.cr.volces.com/library/nginx:stable-alpine3.23-perl
ports:
- containerPort: 80

Method 2: Use Kyverno to replace the access domain name

Use Kyverno to automatically replace the access domain name when deploying Kubernetes applications.

Install Kyverno.

Create a policy.

tip

Copying the following YAML, replace both occurrences of [System domain name] with the access domain name obtained in Step 1. The two occurrences are in the image fields under initContainers and containers.

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
name: replace-image-registry-with-harbor
annotations:
policies.kyverno.io/title: Replace Image Registry With Harbor
pod-policies.kyverno.io/autogen-controllers: none
policies.kyverno.io/category: Sample
policies.kyverno.io/severity: medium
policies.kyverno.io/subject: Pod
kyverno.io/kyverno-version: 1.11.4
kyverno.io/kubernetes-version: "1.27"
policies.kyverno.io/description: >-
Some registries like Harbor offer pull-through caches for images from certain registries.
Images can be re-written to be pulled from the redirected registry instead of the original and
the registry will proxy pull the image, adding it to its internal cache.
The imageData context variable in this policy provides a normalized view
of the container image, allowing the policy to make decisions based on various
"live" image details. As a result, it requires access to the source registry and the existence
of the target image to verify those details.
spec:
rules:
- name: redirect-docker
match:
any:
- resources:
kinds:
- Pod
operations:
- CREATE
- UPDATE
mutate:
foreach:
- list: request.object.spec.initContainers[]
context:
- name: imageData
imageRegistry:
reference: "{{ element.image }}"
preconditions:
any:
- key: "{{imageData.registry}}"
operator: Equals
value: index.docker.io
patchStrategicMerge:
spec:
initContainers:
- name: "{{ element.name }}"
image: [System domain name]/{{imageData.repository}}:{{imageData.identifier}}
- list: request.object.spec.containers[]
context:
- name: imageData
imageRegistry:
reference: "{{ element.image }}"
preconditions:
any:
- key: "{{imageData.registry}}"
operator: Equals
value: index.docker.io
patchStrategicMerge:
spec:
containers:
- name: "{{ element.name }}"
image: [System domain name]/{{imageData.repository}}:{{imageData.identifier}}

Deploy the application by using the image address nginx:stable-alpine3.23-perl.

Last updated: 2026.10.19 15:46:48