Geo-Replication

When an image is pushed to a source registry, the replication engine copies it to target registries in other regions without blocking the push operation. This decouples the developer workflow from the replication process.

• Event-driven: Triggered by on_push events, not polling
• Store-and-forward: Queues replication tasks to handle transient network failures
• Selective filtering: Replicate only images matching specific namespaces, tags, or labels

Example: A build pipeline in us-east pushes app:v1.2. The registry immediately returns success and asynchronously replicates the manifest and all referenced blobs to eu-west and ap-southeast.

A registry instance acts as a transparent cache for an upstream source. When a client requests an image not present locally, the registry fetches it from the remote, stores a copy, and serves it to the client. Subsequent pulls are served from the local cache.

• Bandwidth conservation: Eliminates repeated pulls over WAN links
• Offline resilience: Cached images remain available during upstream outages
• Immutability guarantee: Content-addressable layers ensure cached blobs match the original

This pattern is critical for air-gapped environments where a registry mirror in the secure network proxies approved external images.

Replication rules define exactly which artifacts move between registry instances, preventing namespace collisions and ensuring deterministic state across regions.

• Source/target mapping: Define source-registry/namespace -> target-registry/namespace pairs
• Tag filtering: Replicate only prod-* tags, excluding ephemeral dev-* builds
• Override protection: Configure whether existing tags at the target are overwritten or preserved
• Bandwidth scheduling: Throttle replication during peak hours to avoid saturating inter-region links

A typical policy replicates all production/* images bidirectionally between three regions while excluding staging/* entirely.

Geo-replication operates at the content-addressable blob layer, not the image level. When replicating, only unique blobs not already present at the target are transferred.

• Hash-based identification: Each blob is identified by its SHA256 digest
• Shared base layers: A Node.js base layer replicated once serves hundreds of derived application images
• Delta efficiency: Only new or modified layers traverse the network

Example: Replicating 50 microservice images built on the same node:20-alpine base transfers the base layer once, then only the thin application layers for each service. This reduces inter-region bandwidth by up to 90%.

Each replicated registry instance continuously reports its availability status. Client-side tooling or load balancers can automatically route pull requests to the nearest healthy instance.

• Heartbeat checks: Registry endpoints probed at configurable intervals
• Latency-aware routing: DNS or Anycast directs clients to the lowest-latency replica
• Degraded mode handling: If a region is unreachable, clients fall back to the next-closest replica
• Replication lag visibility: Metrics expose the time delta between source push and target availability

In a Kubernetes cluster, an admission controller can rewrite image references at deploy time to point to the local registry mirror, ensuring pods always pull from the fastest available source.

Every replication event is recorded in a tamper-proof log, providing a complete chain of custody for container images as they move across jurisdictions.

• Event recording: Source digest, target digest, timestamp, and initiating user for each replication
• SLSA attestation: Replication events can generate signed provenance statements
• Compliance evidence: Prove to auditors that images in eu-data originated from approved us-build pipelines
• Drift detection: Compare expected vs. actual state across replicas to identify unauthorized modifications

This is essential for sovereign cloud deployments where regulators require proof that no unauthorized artifacts entered a jurisdiction's registry.