How to Configure Harbor Cache for Efficient Image Distribution

Introduction

Harbor is a cloud-native registry that provides secure and scalable image management. One of its critical features is caching, which helps optimize image distribution and network consumption in an air-gapped environment. In this guide, we will walk through How to Configure Harbor Cache for Efficient Image Distribution. By the end of this tutorial, you will know how Harbor cache can serve as a pull-through cache for upstream registries.

Procedure

Prerequisites

Before starting, ensure you have the following:

• A running Harbor instance (installed via Docker Compose or Helm on Kubernetes)
• Access to the Harbor Web UI with administrative privileges
• A remote container registry (e.g., Docker Hub, Quay, or another Harbor instance)

Create a Harbor Cache Repository

Before enabling the proxy cache, you need to create a dedicated Harbor repository to store cached images.

Log in to the Harbor Web UI.
Navigate to Administration->Registries and click + New Project.
Choose a Provider (e.g., Docker Registry ).
Enter Name for example: quay.io
Set the Endpoint option based to https://quay.io/v2.
Enter credentials if needed.

Click Test Connection and verify the output:

Click OK to create the repository.

You should see it in the registries table:

Enable the Proxy Cache in Harbor

Log in to the Harbor Web UI as an administrator.
Navigate to Projects and click + New Project.
Select Access Level as Public
Select Proxy Cache as the project type and select the Registry from the drop down (e.g., quay.io ).
Click OK to create the proxy cache project.

Configure CRIO to Use Harbor as a Mirror

Edit the registries.conf file in the worker node with the following configurations to work with the Harbor cache as a mirror.

NOTE: If required, you may cancel the TLS check using insecure = true

$ cat /etc/containers/registries.conf.d/02-docker-io.conf 
[[registry]]
prefix = "registry.hub.docker.com"
insecure = true
blocked = false
location = "registry.hub.docker.com"

[[registry.mirror]]
location = "harbor.k8s.co.il/docker_proxy_cache"
insecure = true

You may cancel the TLS check using the following as well.

$ cat /etc/containers/registries.conf.d/01-unqualified.conf
unqualified-search-registries = ['harbor.k8s.co.il', 'registry.hub.docker.com']

Pull an Image Through Harbor Cache

To test if the cache is working, pull an image:

$ sudo crictl pull harbor.k8s.co.il/docker_proxy_cache/minio/mc:latest
Image is up to date for harbor.k8s.co.il/docker_proxy_cache/minio/mc@sha256:9ae9ed28d04f7c36ee6b84c36b2c0168f1be28350d54344c3e5088a631f4c603

Check if the image is successfully cached in Harbor by navigating to the Proxy Cache project in the Web UI and verifying the presence of the image.

Summary

Configuring Harbor as a caching proxy significantly improves image pull performance by reducing latency and bandwidth usage. In this guide, we enabled a Proxy Cache project in Harbor, configured the CRIO on workers of kubernetes to use it as a mirror, and tested its efficiency. By following these steps, you ensure that your Kubernetes clusters pull container images faster while minimizing dependency on external registries.
Now you know How to Configure Harbor Cache for Efficient Image Distribution. These caching capabilities enhance container security and efficiency.

At Octopus Computer Solutions, we specialize in optimizing Kubernetes and container workflows, including advanced Harbor registry configurations. Our air-gapped and disconnected expertise ensures secure, efficient, and scalable image management for your enterprise.

Enjoy.