Enterprise‑Scale Harbor: Multi‑Arch Migration, Governance & Performance Tips

Harbor in the CI/CD workflow

Developers push code to feature branches, open pull requests, and trigger CI pipelines via webhooks. The pipelines build container images and push them to Harbor, which acts as the central image registry. Testers and automated deployment scripts pull images from Harbor for validation and release.

Scale growth (2019‑2023)

Image count grew from ~500 to >2,000, artifact count from 10,000 to >100,000, and storage from 1 TB to >10 TB. Daily push requests increased from ~1,000 to >50,000 and daily pulls from ~10,000 to >100,000.

Migration from Harbor 1.x to 2.x (multi‑architecture support)

Harbor 1.x stored only single‑architecture images. To support AMD and ARM, two work‑arounds were used:

Deploy separate Harbor instances (AMDHarbor, ARMHarbor) and reference the appropriate registry in Helm charts.

Append architecture suffixes to image tags, which caused tag proliferation.

Harbor 2.0 introduced OCI artifact support, allowing a single tag to reference multiple architectures. Migration steps:

Push each single‑architecture image from the 1.x registry to the 2.x registry, adding a distinct architecture suffix (e.g., myapp:1.0-amd64, myapp:1.0-arm64). If the same tag is pushed twice, the later push overwrites the former, so unique suffixes are required.

Create an OCI manifest index that aggregates the architecture‑specific images and push it to Harbor:

# Example for a Go application
docker manifest create myrepo/myapp:1.0 \
    --amend myrepo/myapp:1.0-amd64 \
    --amend myrepo/myapp:1.0-arm64

docker manifest push myrepo/myapp:1.0

The manifest index is stored in Harbor and can be pulled on any supported architecture.

Build strategies for multi‑arch images

Two approaches were evaluated:

QEMU emulation : Install QEMU on the build host to emulate other architectures. Configuration is simple but build speed is ~5‑6× slower than native builds.

Heterogeneous Kubernetes clusters (buildx driver) : Deploy separate AMD and ARM node pools. Docker Buildx dispatches each architecture build to the matching node, achieving near‑native speed at the cost of managing multiple clusters.

Benchmark using Docker’s official Golang multi‑stage Dockerfile showed the heterogeneous‑cluster Buildx method to be roughly five to six times faster than the QEMU‑based method.

Governance and maintenance policies

Naming convention – Image tags are generated from Git branch names:

Bug‑fix branches: prefix fix‑ Feature branches: prefix feat‑ Timestamp suffix for build identification.

Release branches produce official version tags (e.g., v1.2.3).

Tag retention – Harbor’s Tag Retention policy can automatically delete tags based on:

Number of recent pushes or pulls.

Age in days.

Inclusion/exclusion rules for repositories or tag patterns.

Garbage collection (GC) – After tag deletion, unreferenced image layers remain until GC runs. GC scans all manifests, marks layers still referenced, and removes orphaned layers, preventing storage bloat.

Integration with Lingque Cloud ACP

Harbor is embedded in the ACP platform. Project‑level binding automatically creates matching Harbor projects. A global policy can designate a shared “library” project for common images. Additional policies control image cleanup and protection.

Community contributions

Multi‑Architecture Workgroup maintains architecture‑specific Harbor images:

ARM images: https://github.com/goharbor/harbor-arm

Loongson (国产化) images: https://github.com/goharbor/harbor-loongson

Workgroup repository: https://github.com/goharbor/community/tree/master/workgroups/wg-multiarch

Performance Workgroup provides a performance testing suite and reports:

Toolset: https://github.com/goharbor/perf

Harbor 2.3.0 performance report: https://github.com/goharbor/perf/wiki/Harbor-2.3.0-Performance-Test-Reports

Key issue fixes: https://github.com/goharbor/harbor/issues/14819, https://github.com/goharbor/harbor/issues/14815, https://github.com/goharbor/harbor/issues/14814, https://github.com/goharbor/harbor/issues/14813, https://github.com/goharbor/harbor/issues/14716

Performance testing on a 300‑concurrent‑user workload with 100 k artifacts showed the following improvements in Harbor 2.3 compared with earlier 2.x releases:

Catalog queries: ~3× faster

Project listing: ~4× faster

Artifact retrieval: ~15× faster

Tag operations: ~4× faster

Audit‑log queries: ~10× faster

Harbor Enterprise Edition (technical overview)

The enterprise offering adds high‑availability deployment options (including a Kubernetes Operator), automated version upgrades, vulnerability patching, migration assistance, disaster‑recovery procedures, and integrated DevOps toolchain support.

Key takeaways

Harbor 2.x provides native OCI multi‑arch support, eliminating the need for duplicate registries or tag suffixes.

Use Docker Buildx with heterogeneous clusters for efficient multi‑arch builds.

Adopt strict naming, tag‑retention, and GC policies to control storage growth.

Leverage community workgroups for architecture‑specific images and performance tooling.

Enterprise features deliver HA, automated upgrades, and professional support for production environments.