Global and Cross-Region Design
Explore how Amazon DocumentDB supports global clusters to extend availability and performance across multiple regions. Learn the read-local, write-primary design, client routing, switchover and failover processes, and the importance of version alignment and capacity planning to build resilient, multi-region document database architectures.
Once data flows are established within a single Region through change streams and event-driven patterns, the next architectural question becomes unavoidable. How do you extend availability and read performance when your users, applications, and compliance requirements span multiple continents? A single-Region Amazon DocumentDB cluster, no matter how many read replicas it contains, cannot survive a full Region outage and cannot serve low-latency reads to users thousands of kilometers away. The AWS-native answer for multi-Region document database needs is a
A global cluster follows a strict architecture. One Region holds the primary cluster, which is the only cluster that accepts write operations. Up to ten additional Regions each hold a secondary cluster that serves read traffic from locally replicated data. This is fundamentally different from a single-Region cluster that relies solely on local replicas within one set of Availability Zones.
Two motivations drive this design. The first is low-latency local reads for geographically distributed applications, where a user in Frankfurt reads from a European secondary rather than crossing the Atlantic to a US-based primary. The second is disaster recovery, because if the primary Region becomes entirely unavailable, a secondary Region can be promoted to take over the write role.
Attention: DocumentDB global clusters are frequently confused with Aurora Global Database and DynamoDB global tables. Aurora Global Database uses a similar read-local, write-primary model but applies to relational workloads. DynamoDB global tables support active/active multi-write across Regions. DocumentDB global clusters do not support multi-write, and secondary clusters reject any write traffic unless explicitly promoted.
The following diagram illustrates how a global cluster distributes its components across Regions and how client traffic flows between endpoints.
With the high-level structure in place, the next step is understanding exactly how application traffic interacts with each side of this architecture. ...