Understanding Harbor: Architecture, Features, High Availability, and Image Storage

Harbor is an open‑source enterprise‑grade container image registry developed by VMware, providing a Docker Registry with additional management features such as role‑based access control, project organization, and image replication.

Harbor Architecture

Harbor consists of six components:

Proxy – an Nginx reverse proxy that handles all incoming requests.

Registry – stores Docker images and processes push/pull commands, delegating token requests for access control.

Core services, which include: UI – a web management console (frontend) and backend APIs. Webhook – used for image replication and log updates. Token service – issues tokens when a client request lacks one. Job service – handles image replication tasks. Log collector – gathers logs.

Features Used by 360 HULK

1. User Management – role‑based access control with three roles (Project Admin (MDRWS), Developer (RWS), Guest (RS)) plus a system admin.

2. Project Management – projects group multiple repositories, define permissions, and enable cross‑project image replication with retry mechanisms.

3. Permission Management – supports LDAP or database authentication and token expiration settings.

4. Image Replication – enables multi‑datacenter synchronization, allowing containers in different regions to pull from either a primary or secondary Harbor instance.

5. High Availability – three Harbor instances are fronted by an LVS load balancer, sharing a database and cache to provide fault tolerance.

What Is an Image?

An image is a layered filesystem (UnionFS) built on top of a rootfs; each Dockerfile instruction creates a new read‑only layer, while the topmost layer is writable. Layers are stored using drivers such as overlay2, and the default Docker storage path is /var/lib/docker .

Container Image Mount Details

When a container runs, Docker creates a view layer under /var/lib/docker/overlay2 containing diff , link , lower , merged , and work directories. The layers are organized as:

Read‑only layers (base image).

Init layer – stores system files like /etc/hosts that need to be writable per container.

Writable layer – captures all changes made by the container.

Example commands showing the Docker storage layout:

[root@p22295v zhangzhifei]# ls -lrt /var/lib/docker/

total 156

drwxr-x---   3 root root 4096 Dec 6 2018 containerd

drwx------   4 root root 4096 Dec 6 2018 plugins

...

Running a container:

[root@p22295v zhangzhifei]# docker run -it -d kraken-agent:dev

83555ad8c034682ad885fc9e320bfb1f8b75498b61a1a8684d738c411caa930b

Inspecting mount IDs and layer contents:

[root@p22295v zhangzhifei]# cat /var/lib/docker/image/overlay2/layerdb/mounts/83555ad8c034682ad885fc9e320bfb1f8b75498b61a1a8684d738c411caa930b/mount-id

3695f349587aaa2cdc82fcde1a380c7b567ef870a47e4c28b8b279e4edc9eb40

# read‑only layer

# ls /var/lib/docker/overlay2/65e5cdd72f2995da4c73f2d9b90e8d974b9d2f18829a2479296aaec24e67d185/diff/

bin boot dev etc home lib lib64 media mnt opt proc root run sbin srv sys tmp usr var

All layers are finally merged under the merged directory, presenting a complete filesystem for the container.

mount | grep 3695f349587aaa2cdc82fcde1a380c7b567ef870a47e4c28b8b279e4edc9eb40

overlay on /var/lib/docker/overlay2/3695f349587aaa2cdc82fcde1a380c7b567ef870a47e4c28b8b279e4edc9eb40/merged type overlay (rw,relatime,lowerdir=...)

Image Storage in the Registry

Local storage resides under /data/registry/docker/registry/v2 with a structure like:

├── blobs
│   └── sha256
│       └── dfa94d.../data
│   └── e6/.../data
│   └── e7/.../data
└── repositories
    ├── registry-share-private
    │   ├── push-mount
    │   │   ├── _layers
    │   │   │   └── sha256/.../link
    │   │   ├── _manifests
    │   │   │   ├── revisions/sha256/.../link
    │   │   │   └── tags/v1/current/link
    │   │   └── _uploads

The blobs directory stores compressed layer data and manifest JSON files, while repositories holds metadata such as layer SHA‑256 links, manifest revisions, tags, and temporary upload data.

Image Upload Process

Authenticate and obtain a token.

Check if required layers already exist in the registry.

Upload missing blobs (large blobs in chunks, small blobs via PUT).

After all blobs are uploaded, push the manifest.

If a layer already exists and the client has read permission, Docker mounts the existing layer to avoid re‑uploading, speeding up the push operation.

References are provided for further reading on Docker registry API, overlayfs driver, and related projects.