Build a Highly Available Harbor Registry with Dual-Master Replication

Harbor Overview

Harbor is an enterprise‑grade Docker image registry that adds security, identity, and management features to the open‑source Docker Distribution.

It provides better performance and security for private registry use, improves image transfer efficiency, supports replication across multiple registry nodes, and ensures data and intellectual‑property control within an internal network.

High‑Availability Architecture: Dual‑Master Replication

Master‑Slave Sync

Harbor’s default master‑slave replication synchronises images from a test environment to production in real time.

When many cluster nodes need images, a single registry cannot handle the load; Harbor’s one‑master‑multiple‑slave mode distributes images efficiently.

Images published to one Harbor instance are automatically replicated to other registries, similar to “fairy dust”.

For geographically dispersed clusters, a hierarchical sync can be used (headquarters → branch 1 → branch 2).

Master‑slave alone does not solve the single‑point‑of‑failure of the primary node.

Dual‑Master Replication

Dual‑master reuses master‑slave sync to achieve bidirectional synchronization between two Harbor nodes, with a load balancer in front to distribute requests. When any instance receives a new image, it is automatically replicated to the other, providing load balancing and avoiding single‑node failure.

If one instance fails and later recovers, the other instance will not automatically sync new images; manual intervention is required to restart the replication strategy.

In practice, master‑slave replication is unreliable; the following solution is recommended.

High‑Availability Architecture: Multi‑Instance Shared Backend Storage

Solution Overview

Multiple Harbor instances share a common backend storage (e.g., NFS). Any instance can read images persisted in the shared storage. A front‑end load balancer distributes requests among instances, achieving load balancing and eliminating single‑point failures.

The demo uses NFS for Harbor data, separates PostgreSQL and Redis for shared use, and employs Nginx as the load balancer.

If the production cluster has many servers and a single load‑balanced Harbor cannot meet demand, a hierarchical architecture can be used: downstream Harbor nodes sync from the primary node and then distribute images to production servers.

Three key considerations for deployment:

Choose shared storage (AWS S3, OpenStack Swift, Ceph, or NFS in the demo).

Share session storage via Redis (default in recent Harbor versions).

Deploy an external database for Harbor instances.

Environment Details

Operating System: CentOS 7.6 Software versions: Docker 19.03.8, docker‑compose 1.25.5, Harbor 1.10.2, Nginx 1.14.0, PostgreSQL 9.6.17, Redis 3.2.12

Installation Steps

Docker

Install dependencies:

yum install -y yum-utils \
  device-mapper-persistent-data \
  lvm2

Install Docker via official script:

curl -fsSL get.docker.com -o get-docker.sh
sh get-docker.sh --mirror Aliyun

Add kernel parameters and enable IPv4 forwarding:

tee -a /etc/sysctl.conf <<-EOF
net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1
EOF
sysctl -p

Configure Docker to use a domestic mirror:

curl -sSL https://get.daocloud.io/daotools/set_mirror.sh | sh -s https://pclhthp0.mirror.aliyuncs.com

Enable and start Docker:

systemctl enable docker && systemctl start docker

Docker‑Compose

Download the binary, give it executable permission, and install bash completion.

# curl -L https://github.com/docker/compose/releases/download/1.24.1/docker-compose-$(uname -s)-$(uname -m) > /usr/local/bin/docker-compose
# chmod +x /usr/local/bin/docker-compose
# curl -L https://raw.githubusercontent.com/docker/compose/1.24.1/contrib/completion/bash/docker-compose > /etc/bash_completion.d/docker-compose

NFS

Server

Install packages: yum -y install nfs-utils rpcbind Create shared directory:

mkdir -p /data/harbor_data
chown nobody:nobody /data/harbor_data

Export the directory:

echo "/data/harbor_data 192.168.166.0/24(rw,sync,no_root_squash)" >> /etc/exports

Enable and start services:

systemctl enable rpcbind && systemctl restart rpcbind
systemctl enable nfs && systemctl restart nfs

Client

Install nfs-utils.

Verify connectivity: # showmount -e 192.168.166.122 Create mount point and add to /etc/fstab:

mkdir /data
192.168.166.122:/data/harbor_data  /data  nfs defaults 0 0

Mount all:

mount -a

PostgreSQL

Install repository and PostgreSQL 9.6:

wget https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
rpm -ivh pgdg-redhat-repo-latest.noarch.rpm
yum -y install postgresql96-server postgresql96-contrib

Initialize and start the database:

/usr/pgsql-9.6/bin/postgresql96-setup initdb
systemctl enable postgresql-9.6 && systemctl restart postgresql-9.6

Set password for user postgres, enable remote access in postgresql.conf (set listen_addresses='*') and add host entries in pg_hba.conf for the Harbor nodes.

Restart PostgreSQL.

Redis

Install Redis: yum -y install redis Modify /etc/redis.conf to bind to 0.0.0.0 and set daemonize yes.

Enable and start Redis:

systemctl enable redis && systemctl restart redis

Harbor

Upload the offline installer harbor-offline-installer-v1.10.2.tgz to the server and extract it to /usr/local/.

tar -xvf harbor-offline-installer-v1.10.2.tgz -C /usr/local/

Edit harbor.yml:

Set hostname to the node IP.

Comment out the HTTPS section.

Set harbor_admin_password.

Set data_volume to /data (the NFS mount).

Comment out database and clair sections.

Enable external_database and external_redis and fill in the PostgreSQL and Redis addresses.

Generate required files: ./prepare Install Harbor:

./install.sh

Nginx Load Balancer

Create an upstream with the two Harbor nodes and configure HTTP→HTTPS redirection and proxy rules for / and /v2/ paths.

# cat harbor.example.com.conf
upstream harbor {
    ip_hash;
    server 192.168.166.81:80;
    server 192.168.166.212:80;
}
server {
    listen 80;
    server_name harbor.example.com;
    rewrite ^(.*) https://$server_name$1 permanent;
}
server {
    listen 443 ssl;
    server_name harbor.example.com;
    ssl_certificate ...crt;
    ssl_certificate_key ...key;
    client_max_body_size 0;
    location / {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_pass http://harbor;
    }
    location /v2/ {
        proxy_pass http://harbor/v2/;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_request_buffering off;
    }
}

Reload Nginx to apply changes:

nginx -s reload