goharbor / goharbor/website

Add configuration examples for using Harbor as a pull-through cache / registry mirror with containerd and CRI-O

Open
#724 3 comments 2 reactions 0 assignees View on GitHub
Dominant language
HTML
Stars
46
Forks
222
PR merge metrics
No merged PRs in 30d

Description

## Expected behavior and actual behavior

The Harbor website/documentation currently lacks practical configuration examples for using Harbor as a registry mirror (pull-through cache) with common container runtimes such as:

- containerd
- CRI-O
- containers/image based tooling (Podman, Buildah, Skopeo on Red Hat systems)

There are examples and explanations for Harbor proxy cache projects, but there is no end-to-end documentation showing how clients should configure their runtimes to pull images from Harbor instead of directly from upstream registries like:

- docker.io
- quay.io
- ghcr.io
- ...

This makes adoption more difficult, especially for Kubernetes and OpenShift environments.

## Steps to reproduce the problem

1. Configure a Harbor Proxy Cache project for `docker.io` or `quay.io`.
2. Search the Harbor documentation for runtime/client configuration examples
3. Try to configure:
- containerd
- containers
4. Notice that no dedicated examples or best practices are documented. Instead, only the official configuration of containers and containerd is available.

## Proposed solution

Add a dedicated documentation section such as:

- "Using Harbor as a Registry Mirror"
- "Configuring container runtimes with Harbor Proxy Cache"

The documentation should include practical examples for:

### containerd

Example `hosts.toml` or `config.toml` configuration for mirroring docker.io and quay.io via Harbor.

Example topics:
- `plugins."io.containerd.grpc.v1.cri".registry`
- `config_path`
- `hosts.toml`
- TLS / custom CA handling
- authentication examples

### CRI-O

Examples for:
- `/etc/containers/registries.conf`
- mirror configuration
- insecure registry handling

## Additional context

This would significantly improve the usability of Harbor Proxy Cache projects in:

- Kubernetes environments
- air-gapped setups
- enterprise environments with restricted outbound access

It would also reduce confusion around the difference between:

- Harbor proxy cache configuration
- client-side runtime mirror configuration
- If the `/v2` prefix needs to be configured via `overwrite` in containerd
- Would avoid discussions like [How to configure Harbord to be a mirror registry for Containerd?](https://github.com/goharbor/harbor/issues/18530)

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.