Managing an Amazon DocumentDB global cluster
You perform most management operations on the individual clusters that make up a global cluster. When you choose Group related resources on the Clusters page in the console, you see the primary cluster and secondary clusters grouped under the associated global cluster.
The Configuration tab for a global cluster shows the AWS Regions where the clusters are running, the version, and the global cluster identifier.
Topics
Modifying an Amazon DocumentDB global cluster
The Clusters page in the AWS Management Console lists all your global clusters, showing the primary cluster and secondary clusters for each one. The global cluster has its own configuration settings. Specifically, it has regions associated with its primary and secondary clusters.
When you make changes to the global cluster, you have a chance to cancel changes.
When you choose Continue, you confirm the changes.
Modifying parameters an Amazon DocumentDB global cluster
You can configure the cluster parameter groups independently for each cluster within the global cluster. Most parameters work the same as for other kinds of Amazon DocumentDB clusters. We recommend that you keep settings consistent among all the clusters in a global database. Doing this helps to avoid unexpected behavior changes if you promote a secondary cluster to be the primary.
For example, use the same settings for time zones and character sets to avoid inconsistent behavior if a different cluster takes over as the primary cluster.
Removing a cluster from an Amazon DocumentDB global cluster
There are several situations when you may want to remove clusters from your global cluster. For example, you might want to remove a cluster from a global cluster if the primary cluster becomes degraded or isolated. It then becomes a standalone provisioned cluster that could be used to create a new global cluster. To learn more, see Manually recovering a global cluster from an unplanned outage.
You also might want to remove clusters because you want to delete a global cluster that you no longer need. You can't delete the global cluster until after you detach all associated clusters, leaving the primary for last. For more information, see Deleting an Amazon DocumentDB global cluster.
Note
When a cluster is detached from the global cluster, it's no longer synchronized with the primary. It becomes a standalone provisioned cluster with full read/write capabilities. Additionally, it is no longer visible in the Amazon DocumentDB console. It is only visible when you select the region in the console that the cluster was located in.
You can remove clusters from your global cluster using the AWS Management Console, the AWS CLI, or the RDS API.
Deleting a cluster from an Amazon DocumentDB global cluster
To delete an global cluster, do the following:
-
Remove all secondary clusters from the global cluster. Each cluster becomes a standalone cluster. See the previous section, Removing Global Clusters.
-
From each standalone cluster, delete all replicas.
-
Remove the primary cluster from the global cluster. This becomes a standalone cluster.
-
From the primary cluster, first delete all replicas, then delete the primary instance. Deleting the primary instance from the newly standalone cluster also typically removes both the cluster and the global cluster.
Creating a headless Amazon DocumentDB cluster in a secondary region
Although an Amazon DocumentDB global cluster requires at least one secondary cluster in a different AWS Region than the primary, you can use a headless configuration for the secondary cluster. A headless secondary Amazon DocumentDB cluster is one without an instance. This type of configuration can lower expenses for a global cluster. In an Amazon DocumentDB cluster, compute and storage are decoupled. Without the instance, you're not charged for compute, only for storage. If it's set up correctly, a headless secondary's storage volume is kept in sync with the primary cluster.
You add the secondary cluster as you normally do when creating an Amazon DocumentDB global cluster. However, after the primary cluster begins replication to the secondary, you delete the read-only instance from the secondary cluster. This secondary cluster is now considered "headless" because it no longer has a Instance. Yet, the storage volume is kept in sync with the primary Amazon DocumentDB cluster.
Important
We only recommend headless clusters for customers who can tolerate region-wide failures for 15+ minutes. This is because recovering from a region-wide failure with a headless secondary cluster will require the user to create a new instance after failing over. A new instance can take ~10-15 minutes to become available.
How to Add a Headless Secondary Cluster to Your Global Cluster
-
Sign in to the AWS Management Console and open the Amazon DocumentDB console
. -
Choose Clusters on the left side navigation.
-
Choose the global cluster that needs a secondary cluster. Ensure that the primary cluster is
Available
. -
For Actions, choose Add region.
-
On the Add a region page, choose the secondary region.
Note
You can't choose a region that already has a secondary cluster for the same global cluster. Also, it can't be the same region as the primary cluster.
-
Complete the remaining fields for the secondary cluster in the new region. These are the same configuration options as for any cluster instance.
-
Add a region. After you finish adding the region to your global cluster, you will see it in the list of
Clusters
in the AWS Management Console. -
Check the status of the secondary cluster and its reader instance before continuing, by using the AWS Management Console or the AWS CLI. Here is a sample command if you use the AWS CLI:
$ aws docdb describe-db-clusters --db-cluster-identifier secondary-cluster-id --query '*[].[Status]' --output text
It can take several minutes for the status of a newly added secondary cluster to change from creating to available. When the cluster is available, you can delete the reader instance.
-
Select the reader instance in the secondary cluster, and then choose Delete.
-
After deleting the reader instance, the secondary cluster remains part of the global cluster. It should have no instance associated with it.
Note
You can use this headless secondary Amazon DocumentDB cluster to manually recover your Amazon DocumentDB global cluster from an unplanned outage in the primary region if such an outage occurs.