Image Syncer Overview

image-syncer is a fast and flexible registry-to-registry container image synchronization tool. It is designed to copy images between major Docker Registry V2 compatible services (including Alibaba Cloud ACR, Docker Hub, Quay.io, Harbor, and others) securely and efficiently.

Unlike traditional methods that require pulling, tagging, and pushing images through a local Docker daemon, image-syncer operates directly on raw registry payloads over the network. By eliminating local image layer storage and decompression, it significantly reduces transfer times, disk wear, and network consumption.

Core Operating Concept

Traditional workflows require a local container engine (like Docker or containerd) to pull the image layers, unpack them onto the local filesystem, update local tag references, repackage them, and push them to the target. This approach introduces bottlenecking on local disk I/O, unnecessary CPU usage during compression/decompression, and requires root or privileged engine access.

image-syncer operates entirely in-memory and on-the-fly. It establishes a direct network pipeline between the source registry and the destination registry. When synchronization is initiated, the tool fetches the manifest from the source, determines the required blobs (layers), checks if those blobs already exist at the destination, and copies missing blobs by streaming network payloads directly. The local host serves strictly as a network pipe and memory buffer.

Key Architectural Features

  • Many-to-Many Registry Synchronization: Synchronize multiple image repositories and tags across distinct source and destination registries using a single configuration and execution task.
  • In-Memory Streaming (No Disk Footprint): Layer blobs are downloaded into memory buffers and streamed directly to the target. This enables execution on minimal cloud instances, ephemeral CI/CD runners, or container platforms with strict disk quotas.
  • Incremental Synchronization (Deduplication): Before transferring layers, image-syncer queries the destination registry. It avoids redundant transfers by skipping layers and manifests that are already present at the target, optimizing bandwidth consumption.
  • High-Throughput Concurrency: Utilizing a pool of goroutines, the application executes concurrent transfers of image blobs. The level of concurrency is fully adjustable via configuration parameters to suit the available network bandwith.
  • Multi-Architecture Filtering: Users can opt to target specific platforms. For multi-architecture manifests (manifest lists), image-syncer can filter and synchronize only designated Operating Systems (e.g., Linux, Windows) and Architectures (e.g., AMD64, ARM64), saving target storage space.
  • Transient Failure Recovery: Built-in retry mechanisms handle network anomalies, TLS handshake timeouts, and registry rate limits. If a layer upload fails midway, the tool retries the operation dynamically.
  • Daemonless Architecture: Operates as a static Go binary with zero external dependencies. It does not require a running Docker daemon, making it highly secure and easy to deploy in isolated runtime environments.

When to Use image-syncer

  • Multi-Cloud and Multi-Region Redundancy: Distributing production container images across different cloud vendors (e.g., from AWS ECR to Alibaba Cloud ACR) or across geographically isolated registry nodes to ensure localized pull speeds and high availability.
  • Air-Gapped and Private Registry Seeding: Moving third-party open-source images from public registries (such as Docker Hub or Quay.io) to internal secure enterprise registries.
  • CI/CD Pipeline Distribution: Integrating into deployment pipelines where images built in a staging registry must be transferred securely to production environments across different security domains.
  • Registry Migration: Relocating large-scale catalogs of historical images from old or self-hosted registries to modern cloud-managed container registries.

Supported Registry Ecosystems

image-syncer works with registries conforming to the Docker Registry V2 or OCI Distribution specifications, including:

  • Alibaba Cloud Container Registry (ACR) Enterprise and Personal editions
  • Docker Hub (Official and private organization repositories)
  • Quay.io
  • Harbor (Private and Enterprise deployments)
  • Google Container Registry (GCR) / Artifact Registry
  • AWS Elastic Container Registry (ECR)
  • Local registries running the standard registry:2 image

To begin installation and setup, see Installation and Setup. To run your first synchronization, follow the Quick Start Guide.