AWS Database Blog

Use headless clusters in Amazon DocumentDB for cost-effective multi-Region resiliency

Amazon DocumentDB (with MongoDB compatibility) is a highly efficient, scalable, and fully managed enterprise document database service designed to handle native JSON workloads. Amazon DocumentDB simplifies storing, querying, and indexing JSON data as a document database.

Maintaining resilience to handle AWS Region-wide events that may cause databases running in a degraded state is crucial for organizations with mission-critical workloads. The establishment of a budget-friendly disaster recovery strategy is necessary to uphold uninterrupted business continuity and meet regulatory obligations.

The Amazon DocumentDB headless cluster feature allows for the efficient maintenance of a low-cost data copy across Regions and failover to one of the secondary clusters in a disaster recovery situation. For a thorough understanding of pricing and Regional availability, refer to Amazon DocumentDB (with MongoDB compatibility) pricing.

In this post, we discuss how to create a headless cluster in a secondary Region.

Solution overview

An Amazon DocumentDB global cluster has one primary and up to five secondary Regions. The primary cluster has read/write capabilities and replicates the data to the secondary clusters with little impact on performance, with a typical lag of less than 1 second.

With Amazon DocumentDB, you can create a secondary cluster without compute instances attached to the cluster. This feature enhances data durability while reducing costs.

Secondary clusters with compute have the following configuration:

  • Each secondary cluster can hold up to 16 replica instances. These instances are restricted to read-only access.
  • In the event of an outage in the primary Region, it is possible to promote the secondary cluster to the primary in typically under 1 minute.

Secondary clusters without compute (headless) have the following configuration:

  • The secondary cluster is still receiving data at the storage level from the primary cluster.
  • In the event of an outage in the primary Region, instances must be added to the secondary cluster, which takes 10-15 minutes. However, the cost remains low because there are no compute expenses incurred in the secondary Region.

The following diagram illustrates the architecture of a headless cluster.

You can establish an Amazon DocumentDB headless cluster using one of the following methods:

Convert an Amazon DocumentDB cluster to a global cluster with a headless configuration – You can create an Amazon DocumentDB global cluster with a headless configuration by adding a secondary cluster without a database instance, thereby transforming the secondary cluster into a headless cluster

Modify an existing Amazon DocumentDB global cluster to create a headless configuration – To convert a secondary Region cluster into a headless configuration, delete all replica instances attached to it

We discuss both methods in this post.

Prerequisites

  • A minimum requirement for setting up an Amazon DocumentDB headless cluster is the presence of an Amazon DocumentDB standalone cluster. You can use an existing Amazon DocumentDB cluster or create a new one.
  • To follow along with the examples, you need to have the AWS Command Line Interface (AWS CLI) installed and configured with your AWS credentials and a default Region. Some of the examples use syntax that requires the AWS CLI v2. For instructions on installing, upgrading, or configuring the AWS CLI, refer to Install or update the latest version of the AWS CLI.

Convert an Amazon DocumentDB standalone cluster to a global cluster with a headless configuration

You can convert an Amazon DocumentDB cluster into a global headless cluster by adding a secondary Region with no instances. Complete the following steps:

  1. On the Amazon DocumentDB console, choose Clusters in the navigation pane. This page lists the information about the primary region cluster.

    You can also use the AWS CLI:

    aws docdb describe-db-clusters --region us-east-1 --query 'DBClusters[].{DBClusterIdentifier:DBClusterIdentifier,Endpoint:Endpoint,ReaderEndpoint:ReaderEndpoint,DBClusterArn:DBClusterArn,EngineVersion:EngineVersion}'
  2. Run the following AWS CLI command to convert the Amazon DocumentDB primary cluster into a global cluster: 
    aws docdb create-global-cluster --global-cluster-identifier docdb-global-cluster --source-db-cluster-identifier arn:aws:rds:us-east-1:111111111111:cluster:docdb-useast
  3. Return to the Amazon DocumentDB console and validate the cluster configuration.
  4. Add the secondary cluster to the global cluster using the following AWS CLI command. 
    aws docdb create-db-cluster --engine docdb --global-cluster-identifier docdb-global-cluster --region us-west-2 --db-cluster-identifier docdb-uswest --kms-key-id aaaaaaaa-1aaa-1111-a1a1-1aaa11a11aa1
  5. Review the cluster configuration on the Amazon DocumentDB console. The transition of the status from Creating to Available for a newly added secondary Region cluster may take several minutes.

The secondary Region cluster has been integrated into the global cluster of Amazon DocumentDB, with no replica instances. By implementing this approach, you have successfully transformed your Amazon DocumentDB cluster into an Amazon DocumentDB global cluster with a headless configuration.

Modify an existing Amazon DocumentDB global cluster to create a headless configuration

You can delete the replica instances of an existing Amazon DocumentDB global cluster to convert it to a headless configuration. Complete the following steps:

  1. On the Amazon DocumentDB console, choose Clusters in the navigation pane. This page lists the information about the global cluster.
  2. To delete the existing replica instances attached to the secondary cluster, select the replica and choose Delete on the Actions menu.

    It may take a few minutes for the deletion of the instance to complete.
  3. Review the configuration of the cluster on the Clusters page.

The storage of the secondary cluster remains intact, and the data continues to be replicated at the storage level to maintain synchronization. The secondary Region cluster no longer has instances attached to it. With this approach, you have modified an existing Amazon DocumentDB global cluster into a headless configuration.

Clean up

To avoid ongoing costs, clean up the resources you no longer need that you created as part of this solution. You can use the AWS Management Console or AWS CLI (using delete-db-cluster) to delete the Amazon DocumentDB cluster you created.

Conclusion

Using Amazon DocumentDB headless clusters offers a cost-effective approach for establishing multi-Region resiliency. This feature enables you to achieve sub-second latency, as offered by Amazon DocumentDB global clusters, without incurring additional expenses for unused instances in the secondary Region. After instances are added to the cluster in that Region, the secondary Region can be made accessible to both users and applications. The standard procedure for failing over with headless clusters is the same as with global clusters. For more information, see Failover for Amazon DocumentDB Global Clusters.

If you have any inquiries or suggestions, share them in the comments section.

About the Author

Karimulla Shaik is a Sr. DB Specialty Architect with the Professional Services team at Amazon Web Services. He helps customers migrate traditional on-premise databases to the AWS Cloud. He specializes in database design, architecture, and performance tuning.