# Overview of Amazon DocumentDB global clusters
## What is a global cluster?
A global cluster consists of one primary region and up to 10 read-only secondary regions. You issue write operations directly to the primary cluster in the primary region and Amazon DocumentDB automatically replicates the data to the secondary regions using dedicated infrastructure. Latency is typically under a second.
## How are global clusters useful?
+ **Recovery from region-wide outages ** — In the event of a region-wide outage, you can promote one of the secondary clusters to a primary cluster within minutes, with a typical Recovery Time Objective (RTO) of under a minute. The Recovery Point Objective (RPO) is typically measured in seconds, but this depends on the lag across the network at the time of the failure.
+ **Global reads with local latency ** — If you have offices around the world, you can use a global cluster to keep your main sources of information updated in the primary region. Offices in your other regions can access the information in their own region, with local latency.
+ **Scalable secondary clusters ** — You can scale your secondary clusters by adding more read-only instances to a secondary region. The secondary cluster is read-only, so it can support up to 16 read-only replica instances rather than the usual limit of 15 for a single cluster.
+ **Fast replication from primary to secondary clusters** — The replication performed by a global cluster has little performance impact on the primary database cluster. The resources of the DB instances are fully devoted to serve application read and write workloads.
## What are the current limitations of global clusters?
+ Global clusters are not supported on Amazon DocumentDB v3.6.
+ Global clusters are supported on all instance types except db.t3, db.t4g, and db.r4.
+ Global clusters are not available in the following Regions: South America (São Paulo), Europe (Milan), China (Beijing), and China (Ningxia).
+ Switchover and global failover are not supported when regions are on different engine versions. Manual failover is supported when there's an engine version mismatch.
+ Only the primary cluster performs write operations. Clients that perform write operations connect to the cluster endpoint of the primary cluster.
+ You can have a maximum of 10 secondary regions and one primary region for your cluster.
+ A secondary cluster cannot be stopped. A primary cluster cannot be stopped if it has secondary clusters associated with it. Only a regional cluster that has no secondary clusters can be stopped.
+ Replicas attached to the secondary cluster can restart under certain circumstances. If the primary region's instance restarts or fails over, replicas in the secondary region also restart. The cluster is then unavailable until all replicas are back in sync with the primary database cluster's writer instance. This behavior is expected. Be sure that you understand the impact to your global cluster before making changes to your primary cluster.
+ You cannot use change streams on secondary clusters.
**Topics**
+ [
## What is a global cluster?
](#w2aac35b9b3)
+ [
## How are global clusters useful?
](#w2aac35b9b5)
+ [
## What are the current limitations of global clusters?
](#w2aac35b9b7)
+ [Quick start guide](global-clusters.get-started.md)
+ [Managing global clusters](global-clusters.manage.md)
+ [Connecting global clusters](global-clusters-connect.md)
+ [Monitoring global clusters](global-clusters-monitor.md)
+ [Disaster recovery](global-clusters-disaster-recovery.md)
# Quick start guide: global clusters
**Topics**
+ [Configuration](#global-clusters.config)
+ [Creating a global cluster](#global-clusters-create)
+ [Adding a Region to a global cluster](#global-clusters.add-region)
+ [Using a snapshot](#global-clusters.snapshot)
## Configuration
Amazon DocumentDB global cluster spans at least two AWS Regions. The primary Region supports a cluster that has one primary (writer) instance and up to 15 replica instances, while a secondary Region runs a read-only cluster made up entirely of up to 16 replica instances. A global cluster can have up to five secondary Regions. The table lists the maximum clusters, instances, and replicas allowed in a global cluster.
| Description | Primary AWS Region | Secondary AWS Region |
| --- | --- | --- |
| Clusters | 1 | 5 (maximum) |
| Writer instances | 1 | 0 |
| Read-only instances (Amazon DocumentDB replicas), per cluster | 15 (max) | 16 (total) |
| Read-only instances (max allowed, given actual number of secondary Regions) | 15 - s | s = total number of secondary AWS Regions |
The clusters have the following specific requirements:
+ **Database instance class requirements** — You can only use the `db.r5` and `db.r6g` instance classes.
+ **AWS Region requirements** — The primary cluster must be in one Region, and at least one secondary cluster must be in a different Region of the same account. You can create up to five secondary (read-only) clusters, and each must be in a different Region. In other words, no two clusters can be in the same Region.
+ **Naming requirements** — The names you choose for each of your clusters must be unique, across all Regions. You can't use the same name for different clusters even though they're in different Regions.
## Creating an Amazon DocumentDB global cluster
Are you ready to build your first global cluster? In this section we will explain how to create a brand new global cluster with new database clusters and instances, using either the AWS Management Console or AWS CLI with the following instructions.
### Using the AWS Management Console
1. In the AWS Management Console, navigate to **Amazon DocumentDB**.
1. When you get to the Amazon DocumentDB console, choose **Clusters**.
![\[The Clusters page in the Amazon DocumentDB console.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/quick-start/choose-cluster.png)
1. Choose **Create**.
![\[The Create button shown in the upper-right corner of the Clusters table.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/quick-start/choose-create.png)
1. Fill out the **Configuration** section of the **Create Amazon DocumentDB Cluster** form accordingly:
+ **Cluster identifier**: You can either enter a unique identifier for this instance or allow Amazon DocumentDB to provide the instance identifier based on the cluster identifier.
+ Engine version: Choose **4.0.0**
+ Instance class: Choose **db.r5.large**
+ Number of instances: Choose **3**.
![\[Configuration options form for creating an Amazon DocumentDB cluster.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/quick-start/create-config.png)
1. In the **Authentication** section, fill in a master username and master password.
![\[Authentication form to specify a master username and password for a new Amazon DocumentDB cluster.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/quick-start/create-auth.png)
1. Choose **Show advanced settings**.
![\[Show advanced settings toggle button next to Cancel and Create cluster buttons.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/quick-start/show-advanced.png)
1. In the **Network settings** section:
+ Keep default options for **Virtual Private Cloud (VPC)** and **Subnet group**.
![\[Network settings form showing VPC, subnet group, and VPC security groups options. VPC and Subnet group fields have default options selected.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/quick-start/default-vpc-1.png)
+ For **VPC security groups**, **default (VPC)** should already be added.
![\[Network settings form showing default VPC already added.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/quick-start/default-vpc-2.png)
+ Type `DocDB` into the **VPC security groups** field and select **DocDB-Inbound (VFC)**.
![\[DocDB-Inbound VFC selected in VPC security groups dropdown menu.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/quick-start/inbound-vfc.png)
1. For **Cluster options** and **Encryption-at-rest**, leave at default selections.
![\[Cluster options and Encryption-at-rest forms with default options selected.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/quick-start/leave-default-1.png)
1. For **Backup** and **Log exports**, leave at default selections.
![\[Backup and Log exports forms with default options selected.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/quick-start/leave-default-2.png)
1. For **Maintenance**, **Tags**, and **Deletion protection**, leave at default selections.
![\[Maintenance, Tags, and Deletion protection forms with default options selected.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/quick-start/leave-default-3.png)
1. Now click the button that says **Create cluster**.
![\[The Create cluster button shown at the end of the cluster creation process.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/quick-start/create-cluster.png)
### Using the AWS CLI
To create an Amazon DocumentDB Regional cluster, call the [create-global-cluster AWS CLI](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/create-global-cluster.html). The following AWS CLI command creates an Amazon DocumentDB cluster named `global-cluster-id`. For more information on deletion protection, see [Deleting an Amazon DocumentDB cluster](db-cluster-delete.md).
Also, `--engine-version` is an optional parameter that defaults to the latest major engine version. The current default engine version is `5.0.0` (note: Amazon DocumentDB 8.0 is available but must be explicitly specified as `8.0.0`). When new major engine versions are released, the default engine version for `--engine-version` will be updated to reflect the last major engine version. As a result, for production workloads, and especially those that are dependent on scripting, automation, or CloudFormation templates, we recommend that you explicitly specify the `--engine-version` to the intended major version.
If a `db-subnet-group-name` or `vpc-security-group-id` is not specified, Amazon DocumentDB will use the default subnet group and Amazon VPC security group for the given Region.
In the following example, replace each *user input placeholder* with your own information.
For Linux, macOS, or Unix:
```
aws docdb create-db-cluster \
--global-cluster-identifier global-cluster-id \
--source-db-cluster-identifier arn:aws:rds:us-east-1:111122223333:cluster-id
```
For Windows:
```
aws docdb create-db-cluster ^
--global-cluster-identifier global-cluster-id ^
--source-db-cluster-identifier arn:aws:rds:us-east-1:111122223333:cluster-id
```
Output from this operation looks something like the following (JSON format).
```
{
"DBCluster": {
"StorageEncrypted": false,
"DBClusterMembers": [],
"Engine": "docdb",
"DeletionProtection" : "enabled",
"ClusterCreateTime": "2018-11-26T17:15:19.885Z",
"DBSubnetGroup": "default",
"EngineVersion": "4.0.0",
"MasterUsername": "masteruser",
"BackupRetentionPeriod": 1,
"DBClusterArn": "arn:aws:rds:us-east-1:123456789012:cluster:cluster-id",
"DBClusterIdentifier": "cluster-id",
"MultiAZ": false,
"DBClusterParameterGroup": "default.docdb4.0",
"PreferredBackupWindow": "09:12-09:42",
"DbClusterResourceId": "cluster-KQSGI4MHU4NTDDRVNLNTU7XVAY",
"PreferredMaintenanceWindow": "tue:04:17-tue:04:47",
"Port": 27017,
"Status": "creating",
"ReaderEndpoint": "cluster-id.cluster-ro-sfcrlcjcoroz.us-east-1.docdb.amazonaws.com",
"AssociatedRoles": [],
"HostedZoneId": "ZNKXTT8WH85VW",
"VpcSecurityGroups": [
{
"VpcSecurityGroupId": "sg-77186e0d",
"Status": "active"
}
],
"AvailabilityZones": [
"us-east-1a",
"us-east-1c",
"us-east-1e"
],
"Endpoint": "cluster-id.cluster-sfcrlcjcoroz.us-east-1.docdb.amazonaws.com"
}
}
```
It takes several minutes to create the cluster. You can use the AWS Management Console or AWS CLI to monitor the status of your cluster. For more information, see [Monitoring an Amazon DocumentDB cluster's status](monitoring_docdb-cluster_status.md).
**Important**
When you use the AWS CLI to create an Amazon DocumentDB Regional cluster, no instances are created. Consequently, you must explicitly create a primary instance and any replica instances that you need. You can use either the console or AWS CLI to create the instances. For more information, see [Adding an Amazon DocumentDB instance to a cluster](db-instance-add.md) and [CreateDBCluster](API_CreateDBCluster.md) in the Amazon DocumentDB API Reference.
Once your Regional cluster is available, you can add a secondary cluster in another Region with the following instructions: [Adding an AWS Region to an Amazon DocumentDB global cluster](#global-clusters.add-region). When you add a Region, your Regional cluster becomes your primary cluster, and you have a new secondary cluster in the Region you chose.
## Adding an AWS Region to an Amazon DocumentDB global cluster
A global cluster needs at least one secondary cluster in a different Region than the primary cluster, and you can add up to five secondary clusters. Note that for each secondary cluster that you add, you must reduce the number of replicas allowed in the primary cluster by one. For example, if your global cluster has five secondary Regions, your primary cluster can have only 10 (rather than 15) replicas. For more information, see [Configuration requirements of an Amazon DocumentDB global cluster](https://docs.aws.amazon.com/documentdb/latest/developerguide/global-clusters.get-started.html#global-clusters.config).
### Using the AWS Management Console
1. Sign in to the AWS Management Console and open the Amazon DocumentDB console.
1. In the navigation pane, choose **Clusters**.
![\[The Clusters page in the Amazon DocumentDB console.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/quick-start/choose-cluster.png)
1. Choose the cluster that you would like to add a secondary cluster to. Ensure that the cluster is `Available`.
![\[List of regional and global clusters showing available status, with mydocdbglobalcluster highlighted.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/quick-start/choose-cluster-2.png)
1. Select the dropdown list for **Actions** and then choose **Add Region**.
![\[The Actions dropdown on the Clusters interface shows the Add Region option.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/quick-start/add-region.png)
1. On the **Add an AWS Region** page, choose the secondary Region. Note that 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. If this is the first Region you are adding, you will also have to specify a global cluster identifier of your choice.
![\[Choose a secondary region using the dropdown menu on the Add an AWS Region form.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/quick-start/add-region-2.png)
1. Complete the remaining fields for the secondary cluster in the new Region, then select **Create cluster**. After you finish adding the Region, you can see it in the list of **Clusters** in the AWS Management Console.
![\[Final steps of adding a region to a cluster, showing the Configuration form, hourly cost estimate, and Create cluster button.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/quick-start/select-add-region.png)
### Using the AWS CLI
+ Use the `create-db-cluster` CLI command with the name `(--global-cluster-identifier)` of your global cluster. For other parameters, do the following:
+ For `--region`, choose a different AWS Region than that of your primary Region.
+ Choose specific values for the `--engine` and `--engine-version` parameters.
+ For an encrypted cluster, specify your primary AWS Region as the `--source-region` for encryption.
The following example creates a new Amazon DocumentDB cluster and attaches it to the global cluster as a read-only secondary cluster. In the last step, the instance is added to the new cluster.
In the following example, replace each *user input placeholder* with your own information.
For Linux, macOS, or Unix:
```
aws docdb --region secondary-region-id \
create-db-cluster \
--db-cluster-identifier cluster-id \
--global-cluster-identifier global-cluster-id \
--engine-version version \
--engine docdb
aws docdb --region secondary-region-id \
create-db-instance \
--db-cluster-identifier cluster-id \
--global-cluster-identifier global-cluster-id \
--engine-version version \
--engine docdb
```
For Windows:
```
aws docdb --region secondary-region-id ^
create-db-cluster ^
--db-cluster-identifier cluster-id ^
--global-cluster-identifier global-cluster-id ^
--engine-version version ^
--engine docdb
aws docdb --region secondary-region-id ^
create-db-instance ^
--db-cluster-identifier cluster-id ^
--global-cluster-identifier global-cluster-id ^
--engine-version version ^
--engine docdb
```
## Using a snapshot for your Amazon DocumentDB global cluster
You can restore a snapshot of an Amazon DocumentDB cluster to use as the starting point for your global cluster. To do this, you must restore the snapshot and create a new cluster. This will serve as the primary cluster of your global cluster. You can then add another Region to the restored cluster, thus converting it into a global cluster.
# 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 global clusters](#global-clusters.modify)
+ [Modifying parameters](#global-clusters.modify-parameters)
+ [Removing global clusters](#global-clusters.remove)
+ [Deleting global clusters](#global-clusters.delete)
+ [Headless clusters](#global-clusters.headless)
## 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 [Performing a manual failover for an Amazon DocumentDB global cluster](global-clusters-disaster-recovery.md#manual-failover).
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 a cluster from an Amazon DocumentDB global cluster](#global-clusters.delete).
**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.
------
#### [ Using the AWS Management Console ]
1. Sign in to the AWS Management Console and navigate to the Amazon DocumentDB console.
1. Choose **Clusters** on the left side navigation.
![\[Image: the Clusters navigation box showing a list of existing cluster links and their corresponding instance links.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/choose-cluster.png)
1. Expand the global cluster so you can see all the secondary clusters. Select the secondary clusters you wish to remove. Choose **Actions**, and in the menu that drops down, choose **Remove from Global**.
![\[Image: the Clusters navigation box showing the selection of an existing secondary cluster and highlighting the "Remove from global" action.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/remove-global.png)
1. A prompt will appear, asking you to confirm that you want to detach the secondary from the global cluster. Choose **Remove and promote** to remove the cluster from the global cluster.
![\[Image: the Remove and promote prompt.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/remove-promote.png)
Now that cluster is no longer serving as a secondary and no longer synchronized with the primary cluster. It is a standalone cluster with full read/write capability.
After you remove or delete all secondary clusters, then you can remove the primary cluster the same way. You can't detach or remove the primary cluster from the global cluster until after you have removed all secondary clusters. The global cluster might remain in the Clusters list, with zero regions and AZs. You can delete if you no longer want to use this global cluster.
------
#### [ Using the AWS CLI ]
To remove a cluster from a global cluster, run the `remove-from-global-cluster` CLI command with the following parameters:
+ `--global-cluster-identifier` — The name (identifier) of your global cluster.
+ `--db-cluster-identifier` — The name of each cluster to remove from the global cluster.
The following examples first remove a secondary cluster and then the primary cluster from a global cluster.
For Linux, macOS, or Unix:
```
aws docdb --region secondary_region \
remove-from-global-cluster \
--db-cluster-identifier secondary_cluster_ARN \
--global-cluster-identifier global_cluster_id
aws docdb --region primary_region \
remove-from-global-cluster \
--db-cluster-identifier primary_cluster_ARN \
--global-cluster-identifier global_cluster_id
```
Repeat the `remove-from-global-cluster` `--db-cluster-identifier` `secondary_cluster_ARN` command for each secondary region in your global cluster.
For Windows:
```
aws docdb --region secondary_region ^
remove-from-global-cluster ^
--db-cluster-identifier secondary_cluster_ARN ^
--global-cluster-identifier global_cluster_id
aws docdb --region primary_region ^
remove-from-global-cluster ^
--db-cluster-identifier primary_cluster_ARN ^
--global-cluster-identifier global_cluster_id
```
Repeat the `remove-from-global-cluster` `--db-cluster-identifier` `secondary_cluster_ARN` command for each secondary region in your global cluster.
------
## Deleting a cluster from an Amazon DocumentDB global cluster
To delete a global cluster, do the following:
+ Remove all secondary clusters from the global cluster. Each cluster becomes a standalone cluster. See the previous section, [Removing a cluster from an Amazon DocumentDB global cluster](#global-clusters.remove).
+ 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.
------
#### [ Using the AWS Management Console ]
1. Sign in to the AWS Management Console and navigate to the Amazon DocumentDB console.
1. Choose **Clusters** and find the global cluster you want to delete.
![\[Image: the Clusters navigation box showing a list of existing cluster links and their corresponding instance links.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/choose-cluster.png)
1. With your global cluster selected, choose **Delete** from the **Actions** menu.
![\[Image: the Clusters navigation box showing the selection of a global cluster and highlighting the "Delete" action.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/global-clusters/delete-cluster.png)
Confirm that all clusters are removed from the global cluster. The global cluster should show zero regions and AZs and a size of zero clusters. If the global cluster contains any clusters, you can't delete it yet. You’ll first have to follow the instructions in the previous step, **[Removing a cluster from an Amazon DocumentDB global cluster](#global-clusters.remove)**.
------
#### [ Using the AWS CLI ]
To delete a global cluster, run the `delete-global-cluster` CLI command with the name of the AWS Region and the global cluster identifier, as shown in the following example.
For Linux, macOS, or Unix:
```
aws docdb --region primary_region delete-global-cluster \
--global-cluster-identifier global_cluster_id
```
For Windows:
```
aws docdb --region primary_region delete-global-cluster ^
--global-cluster-identifier global_cluster_id
```
------
## 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\$1 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 \$110-15 minutes to become available.
### How to Add a Headless Secondary Cluster to Your Global Cluster
1. Sign in to the AWS Management Console and open the [Amazon DocumentDB console](https://console.aws.amazon.com/rds/).
1. Choose **Clusters** on the left side navigation.
1. Choose the global cluster that needs a secondary cluster. Ensure that the primary cluster is `Available`.
1. For **Actions**, choose **Add region**.
1. 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.
1. Complete the remaining fields for the secondary cluster in the new region. These are the same configuration options as for any cluster instance.
1. 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.
1. 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.
1. Select the reader instance in the secondary cluster, and then choose **Delete**.
1. 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.
# Connect to an Amazon DocumentDB global cluster
How you connect to a global cluster depends on whether you need to write to the cluster or read from the cluster:
+ For read-only requests or queries, you connect to the reader endpoint for the cluster in your AWS Region.
+ To run data manipulation language (DML) or data definition language (DDL) statements, you connect to the cluster endpoint for the primary cluster. This endpoint might be in a different AWS Region than your application.
When you view a global cluster in the console, you can see all the general-purpose endpoints associated with all of its clusters.
How you connect to a global cluster depends on whether you need to write to the database or read from the database. For DDL, DML and read operations that you would like to serve from the primary region, you should connect to your primary cluster. We recommend that you connect to your primary cluster using the cluster endpoint in replica set mode, with a read preference of `secondaryPreferred=true`. This will route write traffic to your primary cluster’s writer instance and read traffic to your primary cluster’s replica instance.
For cross region, read only traffic, you should connect to one of your secondary clusters. We recommend that you connect to your secondary cluster using the cluster endpoint in replica set mode. Since all instances are read-only replica instances, you do not need to specify a read preference. To minimize latency, choose whichever reader endpoint is in your region or the region closest to you.
# Monitoring Amazon DocumentDB global clusters
Amazon DocumentDB (with MongoDB compatibility) integrates with CloudWatch so that you can gather and analyze operational metrics for your clusters. You can monitor these metrics using the CloudWatch console, the Amazon DocumentDB console, the AWS Command Line Interface (AWS CLI), or the CloudWatch API.
To monitor a global cluster, use the following CloudWatch metrics.
| Metric | Description |
| --- | --- |
| GlobalClusterReplicatedWriteIO | The average number of billed write I/O operations replicated from the cluster volume in the primary AWS Region to the cluster volume in a secondary AWS Region, reported at 5-minute intervals. The number of replicated ReplicatedWriteIOs to each secondary region is the same as the number of in-region VolumeWriteIOPs performed by the primary region. |
| GlobalClusterDataTransferBytes | The amount of data transferred from the primary cluster’s AWS Region to a secondary cluster’s AWS Region, measure in bytes. |
| GlobalClusterReplicationLag | The amount of lag, in milliseconds, when replicating change events from the primary cluster’s AWS Region to a secondary cluster’s AWS Region |
For more information on how to view these metrics, please see [Viewing CloudWatch data](https://docs.aws.amazon.com/documentdb/latest/developerguide/cloud_watch.html#cloud_watch-view_data).
# Disaster recovery and Amazon DocumentDB global clusters
**Topics**
+ [
## Performing a managed failover for an Amazon DocumentDB global cluster
](#managed-failover)
+ [
## Performing a manual failover for an Amazon DocumentDB global cluster
](#manual-failover)
+ [
## Performing a switchover for an Amazon DocumentDB global cluster
](#global-cluster-switchover)
+ [
## Unblocking a global cluster switchover or failover
](#unblocking-gc-so-fo)
By using a global cluster, you can recover from disasters such as region failures quickly. Recovery from disaster is typically measured using values for RTO and RPO.
+ **Recovery time objective (RTO)** — The time it takes a system to return to a working state after a disaster. In other words, RTO measures downtime. For a global cluster, RTO in minutes.
+ **Recovery point objective (RPO)** — The amount of data that can be lost (measured in time). For a global cluster, RPO is typically measured in seconds.
+ To recover from an unplanned outage, you can perform a cross-region failover to one of the secondaries in your global cluster. When your global cluster has multiple secondary regions, make sure that you detach all the secondary regions that you wish to promote as primaries. Then, you promote one of those secondary regions to be the new primary AWS Region. Finally, you create new clusters in each of the other secondary regions and attach those clusters to your global cluster.
## Performing a managed failover for an Amazon DocumentDB global cluster
This approach is intended for business continuity in the event of a true Regional disaster or complete service-level outage.
During a managed failover, your primary cluster is failed over to your choice of secondary Region while your Amazon DocumentDB global cluster's existing replication topology is maintained. The chosen secondary cluster promotes one of its read-only nodes to full writer status. This step allows the cluster to assume the role of primary cluster. Your database is unavailable for a short time while this cluster is assuming its new role. Data that wasn't replicated from the old primary to the chosen secondary cluster may be missing when this secondary becomes the new primary. The old primary volume makes a best effort attempt to take a snapshot before synchronizing with the new primary so unreplicated data is preserved on the snapshot.
**Note**
You can only perform a managed cross-Region cluster failover on an Amazon DocumentDB global cluster if the primary and all secondary clusters have the same engine versions. If your engine versions are incompatible, you can perform the failover manually by following the steps in [Performing a manual failover for an Amazon DocumentDB global cluster](#manual-failover).
If the region's engine versions do not match, the failover will be blocked. Please check for any pending upgrades and apply them to ensure all region's engine versions match and the global cluster failover is unblocked. For more information, see [Unblocking a global cluster switchover or failover](#unblocking-gc-so-fo).
To minimize data loss, we recommend that you do the following before using this feature:
+ Take applications offline to prevent writes from being sent to the primary cluster of the Amazon DocumentDB global cluster.
+ Check lag times for all Amazon DocumentDB secondary clusters. Choosing the secondary Region with the least replication lag can minimize data loss with the current failed primary Region. Check lag times for all Amazon DocumentDB secondary clusters in the global cluster by viewing the `GlobalClusterReplicationLag` metric in Amazon CloudWatch. These metrics show you how far behind (in milliseconds) replication to a secondary cluster is to the primary cluster.
For more information about CloudWatch metrics for Amazon DocumentDB, see [Amazon DocumentDB metrics](cloud_watch.md#cloud_watch-metrics_list).
During a managed failover, the chosen secondary cluster is promoted to its new role as primary. However, it doesn't inherit the various configuration options of the primary cluster. A mismatch in configuration can lead to performance issues, workload incompatibilities, and other anomalous behavior. To avoid such issues, we recommend that you resolve differences between your Amazon DocumentDB global clusters for the following:
+ **Configure an Amazon DocumentDB cluster parameter group for the new primary, if necessary** — You can configure your Amazon DocumentDB cluster parameter groups independently for each cluster in your Amazon DocumentDB global clustere. Therefore, when you promote a secondary cluster to take over the primary role, the parameter group from the secondary might be configured differently than for the primary. If so, modify the promoted secondary cluster's parameter group to conform to your primary cluster's settings. To learn how, see [Modifying Amazon DocumentDB cluster parameter groups](cluster_parameter_groups-modify.md).
+ **Configure monitoring tools and options, such as Amazon CloudWatch events and alarms** — Configure the promoted cluster with the same logging ability, alarms, and so on as needed for the global cluster. As with parameter groups, configuration for these features isn't inherited from the primary during the failover process. Some CloudWatch metrics, such as replication lag, are only available for secondary Regions. Thus, a failover changes how to view those metrics and set alarms on them, and could require changes to any predefined dashboards. For more information about Amazon DocumentDB clusters and monitoring, see [Monitoring Amazon DocumentDB](monitoring_docdb.md).
Typically, the chosen secondary cluster assumes the primary role within a minute. As soon as the new primary Region's writer node is available, you can connect your applications to it and resume your workloads. After Amazon DocumentDB promotes the new primary cluster, it automatically rebuilds all additional secondary Region clusters.
Because Amazon DocumentDB global clusters use asynchronous replication, the replication lag in each secondary Region can vary. Amazon DocumentDB rebuilds these secondary Regions to have the exact same point-in-time data as the new primary Region cluster. The duration of the complete rebuilding task can take a few minutes to several hours, depending on the size of the storage volume and the distance between the Regions. When the secondary Region clusters finish rebuilding from the new primary Region, they become available for read access. As soon as the new primary writer is promoted and available, the new primary Region's cluster can handle read and write operations for the Amazon DocumentDB global cluster.
To restore the global cluster's original topology, Amazon DocumentDB monitors the availability of the old primary Region. As soon as that Region is healthy and available again, Amazon DocumentDB automatically adds it back to the global cluster as a secondary Region. Before creating the new storage volume in the old primary Region, Amazon DocumentDB tries to take a snapshot of the old storage volume at the point of failure. It does this so that you can use it to recover any of the missing data. If this operation is successful, Amazon DocumentDB places this snapshot named "rds:docdb-unplanned-global-failover-name-of-old-primary-DB-cluster-timestamp" in the snapshot section of the AWS Management Console. You can also see this snapshot listed in the information returned by the `DescribeDBClusterSnapshots` API operation.
**Note**
The snapshot of the old storage volume is a system snapshot that's subject to the backup retention period configured on the old primary cluster. To preserve this snapshot outside of the retention period, you can copy it to save it as a manual snapshot. To learn more about copying snapshots, including pricing, see [Copying a cluster snapshot](backup_restore-copy_cluster_snapshot.md#backup_restore-copy_a_cluster_snapshot).
After the original topology is restored, you can fail back your global cluster to the original primary Region by performing a switchover operation when it makes the most sense for your business and workload. To do so, follow the steps in [Performing a switchover for an Amazon DocumentDB global cluster](#global-cluster-switchover).
You can fail over your Amazon DocumentDB global cluster using the AWS Management Console, the AWS CLI, or the Amazon DocumentDB API.
------
#### [ Using the AWS Management Console ]
**Perform a managed failover on your Amazon DocumentDB global cluster**
1. Sign in to the AWS Management Console, and open the Amazon DocumentDB console at [https://console.aws.amazon.com/docdb](https://console.aws.amazon.com/docdb).
1. In the navigation pane, choose **Clusters**.
1. Find and choose the Amazon DocumentDB global cluster you want to fail over.
![\[Image: Cluster table with global cluster selected.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/failover-cluster-table.png)
1. Choose **Switchover or Failover** from the **Actions** menu.
1. On the dialog box that appears, choose **Failover**, then choose the secondary cluster from the **New primary cluster** field drop down list.
![\[Image: Global cluster switchover or failover dialog box.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/switch-fail-confirm.png)
1. Type "confirm" in the last field. Then choose **Confirm**.
The status of the primary cluster changes to "**Failing-over**". This condition should take approximately one minute. During this time, the status of the new primary cluster shows "**Modifying...**". Once the new primary is promoted, it will show "**Available**" and will be able to serve read and write transactions. The secondary regions including the old primary will show "**Resyncing...**" while it resynchronizes to the new primary. Similar to the new primary, it will only be able to serve transaction once the status changes to "**Available**".
1. When complete, the original primary cluster becomes the secondary cluster. The selected secondary cluster becomes the primary cluster.
![\[Image: Cluster table showing new primary cluster.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/failover-complete.png)
------
#### [ Using the AWS CLI ]
**Perform a managed failover on your Amazon DocumentDB global cluster**
Run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/failover-global-cluster.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/failover-global-cluster.html) CLI command to fail over your Amazon DocumentDB global cluster. With the command, pass values for the following options:
+ `--region`
+ `--global-cluster-identifier`
+ `--target-db-cluster-identifier`
+ `--allow-data-loss`
In the following examples, replace each *user input placeholder* with your cluster's information.
For Linux, macOS, or Unix:
```
aws docdb failover-global-cluster \
--region region_of_selected_secondary \
--global-cluster-identifier global_cluster_id \
--target-db-cluster-identifier arn_of_secondary_to_promote \
--allow-data-loss
```
For Windows:
```
aws docdb failover-global-cluster ^
--region region_of_selected_secondary ^
--global-cluster-identifier global_cluster_id ^
--target-db-cluster-identifier arn_of_secondary_to_promote ^
--allow-data-loss
```
------
## Performing a manual failover for an Amazon DocumentDB global cluster
If an entire cluster in one AWS Region becomes unavailable, you can promote another cluster in the global cluster to have read/write capability.
You can manually activate the global cluster failover mechanism if a cluster in a different AWS Region is a better choice to be the primary cluster. For example, you might increase the capacity of one of the secondary clusters and then promote it to be the primary cluster. Or the balance of activity among the AWS Regions might change, so that switching the primary cluster to a different AWS Region might give lower latency for write operations.
The following procedure outlines what to do to promote one of the secondary clusters in an Amazon DocumentDB global cluster.
To promote a secondary cluster:
1. Stop issuing DML statements and other write operations to the primary cluster in the AWS Region with the outage.
1. Identify a cluster from a secondary AWS Region to use as a new primary cluster. If you have two (or more) secondary AWS Regions in your global cluster, choose the secondary cluster that has the least lag time.
1. Detach your chosen secondary cluster from the global cluster.
Removing a secondary cluster from a global cluster immediately stops the replication from the primary to this secondary and promotes it to standalone provisioned cluster with full read/write capabilities. Any other secondary cluster associated with the primary cluster in the region with the outage are still available and can accept calls from your application. They also consume resources. Since you are recreating the global cluster, to avoid split-brain and other issues, remove the other secondary clusters before creating the new global cluster in the steps that follow.
For detailed steps for detaching, see [Removing a cluster from an Amazon DocumentDB global cluster](global-clusters.manage.md#global-clusters.remove).
1. This cluster becomes the primary cluster of a new global cluster when you start adding Regions to it, in the next step.
1. Add an AWS Region to the cluster. When you do this, the replication process from primary to secondary begins.
1. Add more AWS Regions as needed to re-create the topology needed to support your application. Make sure that application writes are sent to the correct cluster before, during, and after making changes such as these, to avoid data inconsistencies among the clusters in the global cluster (split-brain issues).
1. When the outage is resolved and you're ready to assign your original AWS Region as the primary cluster again, perform the same steps in reverse.
1. Remove one of the secondary clusters from the global cluster. This will enable it to serve read/write traffic.
1. Redirect all the write traffic to the primary cluster in the original AWS Region.
1. Add an AWS Region to set up one or more secondary clusters in the same AWS Region as before.
Amazon DocumentDB global clusters can be managed using AWS SDKs, enabling you to create solutions to automate global cluster failover process for Disaster Recovery and Business Continuity Planning use cases. One such solution is made available for our customers under Apache 2.0 licensing and can be accessed from our tools repository [here](https://github.com/awslabs/amazon-documentdb-tools/tree/master/global-clusters-automation). This solution leverages Amazon Route 53 for endpoint management and provides AWS Lambda functions that can be triggered based appropriate events.
## Performing a switchover for an Amazon DocumentDB global cluster
By using switchovers, you can change the Region of your primary cluster on a routine basis. This approach is intended for controlled scenarios, such as operational maintenance and other planned operational procedures.
There are three common use cases for using switchovers:
+ For "regional rotation" requirements imposed on specific industries. For example, financial service regulations might want tier-0 systems to switch to a different Region for several months to ensure that disaster recovery procedures are regularly exercised.
+ For multi-Region "follow-the-sun" applications. For example, a business might want to provide lower latency writes in different Regions based on business hours across different time zones.
+ As a zero-data-loss method to fail back to the original primary Region after a failover.
**Note**
Switchovers are designed to be used on a healthy Amazon DocumentDB global cluster. To recover from an unplanned outage, follow the appropriate procedure in [Performing a manual failover for an Amazon DocumentDB global cluster](#manual-failover).
To perform a switchover, all secondary regions must be running the exact same engine version as the primary. If the region's engine versions do not match, the switchover will be blocked. Please check for any pending upgrades and apply them to ensure all region's engine versions match and the global cluster switchover is unblocked. For more information, see [Unblocking a global cluster switchover or failover](#unblocking-gc-so-fo).
During a switchover, Amazon DocumentDB switches over your primary cluster to your chosen secondary Region while it maintains your global cluster's existing replication topology. Before it starts the switchover process, Amazon DocumentDB waits for all secondary Region clusters to be fully synchronized with the primary Region cluster. Then, the DB cluster in the primary Region becomes read-only and the chosen secondary cluster promotes one of its read-only nodes to full writer status. Promoting this node to a writer allows that secondary cluster to assume the role of primary cluster. Because all secondary clusters were synchronized with the primary at the beginning of the process, the new primary continues operations for the Amazon DocumentDB global cluster without losing any data. Your database is unavailable for a short time while the primary and selected secondary clusters are assuming their new roles.
To optimize application availability, we recommend that you do the following before using this feature:
+ Perform this operation during nonpeak hours or at another time when writes to the primary cluster are minimal.
+ Take applications offline to prevent writes from being sent to the primary cluster of the Amazon DocumentDB global cluster.
+ Check lag times for all Amazon DocumentDB secondary clusters in the global cluster by viewing the `GlobalClusterReplicationLag` metric in Amazon CloudWatch. This metric shows you how far behind (in milliseconds) replication to a secondary cluster is to the primary cluster. This value is directly proportional to the time it takes for Amazon DocumentDB to complete the switchover. Therefore, the larger the lag value, the longer the switchover will take.
For more information about CloudWatch metrics for Amazon DocumentDB, see [Amazon DocumentDB metrics](cloud_watch.md#cloud_watch-metrics_list).
During a switchover, the chosen secondary DB cluster is promoted to its new role as primary. However, it doesn't inherit the various configuration options of the primary DB cluster. A mismatch in configuration can lead to performance issues, workload incompatibilities, and other anomalous behavior. To avoid such issues, we recommend that you resolve differences between your Amazon DocumentDB global clusters for the following:
+ **Configure Amazon DocumentDB DB cluster parameter group for the new primary, if necessary** — You can configure your Amazon DocumentDB cluster parameter groups independently for each cluster in your Amazon DocumentDB global cluster. That means that when you promote a secondary DB cluster to take over the primary role, the parameter group from the secondary might be configured differently than for the primary. If so, modify the promoted secondary DB cluster's parameter group to conform to your primary cluster's settings. To learn how, see [Managing Amazon DocumentDB cluster parameter groups](cluster_parameter_groups.md).
+ **Configure monitoring tools and options, such as Amazon CloudWatch Events and alarms** — Configure the promoted cluster with the same logging ability, alarms, and so on as needed for the global cluster. As with parameter groups, configuration for these features isn't inherited from the primary during the switchover process. Some CloudWatch metrics, such as replication lag, are only available for primary Regions. Thus, a switchover changes how to view those metrics and set alarms on them, and could require changes to any predefined dashboards. For more information, see [Monitoring Amazon DocumentDB](monitoring_docdb.md).
**Note**
Typically, the role switchover can take up to several minutes.
When the switchover process completes, the promoted Amazon DocumentDB cluster can handle write operations for the global cluster.
You can switch over your Amazon DocumentDB global cluster using the AWS Management Console or the AWS CLI:
------
#### [ Using the AWS Management Console ]
**Perform a switchover on your Amazon DocumentDB global cluster**
1. Sign in to the AWS Management Console, and open the Amazon DocumentDB console at [https://console.aws.amazon.com/docdb](https://console.aws.amazon.com/docdb).
1. In the navigation pane, choose **Clusters**.
1. Find and select the Amazon DocumentDB global cluster you want to switch over.
![\[Image: Cluster table with global cluster selected.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/switchover-cluster-table.png)
1. Choose **Switchover or Failover** from the **Actions **menu.
1. On the dialog box that appears, choose **Switchover**, then choose the secondary cluster from the **New primary cluster** field drop down list.
![\[Image: Cluster switch over dialog with secondary cluster selected.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/switch-fail-confirm-2.png)
1. Choose **Confirm**.
The status of the primary cluster changes to "**Switching-over**". This condition should take approximately three minutes. During this time, the status of all regional clusters show "**Modifying...**". Once the regions are synchronized and the new primary is promoted, it will show "**Available**" for all status fields and will be able to serve transactions.
1. When complete, the original primary cluster becomes the secondary cluster. The selected secondary cluster becomes the primary cluster.
![\[Image: Cluster table showing new primary cluster.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/failover-complete.png)
------
#### [ Using the AWS CLI ]
**Perform a switchover on your Amazon DocumentDB global cluster**
Run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/switchover-global-cluster.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/switchover-global-cluster.html) CLI command to switch over your Amazon DocumentDB global cluster. With the command, pass values for the following options:
+ `--region`
+ `--global-cluster-identifier`
+ `--target-db-cluster-identifier`
In the following examples, replace each *user input placeholder* with your cluster's information.
For Linux, macOS, or Unix:
```
aws docdb switchover-global-cluster \
--region region_of_primary \
--global-cluster-identifier global_cluster_id \
--target-db-cluster-identifier arn_of_secondary_to_promote
```
For Windows:
```
aws docdb switchover-global-cluster ^
--region region_of_primary ^
--global-cluster-identifier global_cluster_id ^
--target-db-cluster-identifier arn_of_secondary_to_promote
```
------
## Unblocking a global cluster switchover or failover
Global cluster switchovers and failovers are blocked when not all regional clusters in the global cluster are on the same engine version. If the versions do not match, you may see this error in response when calling a switchover or failover: The target DB cluster specified is running an engine version with a different patch level than the source DB cluster. We recommended routinely applying the latest engine versions to ensure you are running the latest updates to keep your global clusters in a healthy state.
To resolve this error, please update all secondary regions first, and then the primary region to the same engine version by applying any pending maintenance action items. To view pending maintenance action items, and to apply any needed changes to correct the issue, perform the instructions in one of the following tabs:
------
#### [ Using the AWS Management Console ]
To unblock a global cluster switchover or failover, you must determine if there are any pending maintenance actions for your clusters and apply them. Follow these steps to view and apply maintenance actions:
1. Sign in to the AWS Management Console, and open the Amazon DocumentDB console at [https://console.aws.amazon.com/docdb](https://console.aws.amazon.com/docdb).
1. In the navigation pane, choose **Clusters**.
1. In the **Clusters** table, locate your global cluster in the **Cluster identifier** column. Under your global cluster, take note of each secondary cluster and the primary cluster for the given global cluster, and perform the following steps for each.
1. For each secondary cluster:
1. If an update is available for your cluster, it is indicated as **Available**, **Required**, or **Next Window** in the **Maintenance** column.
1. To take an action, choose the cluster to show it's details, then choose **Maintenance & backups**. The **Pending Maintenance** items appear.
1. Under **Description**, if it indicates that a "New maintenance update is available", select it and then choose **Apply now**.
1. For your primary cluster:
1. If an update is available for your cluster, it is indicated as **Available**, **Required**, or **Next Window** in the **Maintenance** column.
1. To take an action, choose the cluster to show it's details, then choose **Maintenance & backups**. The **Pending Maintenance** items appear.
1. Under **Description**, if it indicates that a "New maintenance update is available", select it and then choose **Apply now**.
------
#### [ Using the AWS CLI ]
To unblock a global cluster switchover or failover, you must determine if there are any pending maintenance actions for the cluster and apply them. Follow these steps to view and apply maintenance actions first on the secondary clusters then on the primary cluster for your global cluster:
1. Run the following on each secondary region's regional cluster first and then for the primary regions regional cluster.
1. Run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-pending-maintenance-actions.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-pending-maintenance-actions.html) CLI command with the `--resource-identifier` option to determine if any maintenance actions are available for your Amazon DocumentDB regional cluster.
In the following examples, replace each *user input placeholder* with your cluster's information.
For Linux, macOS, or Unix:
```
aws docdb describe-pending-maintenance-action \
--resource-identifier arn:aws:rds:us-east-1:001234567890:cluster:docdb-2025-03-27-19-21-15
```
For Windows:
```
aws docdb describe-pending-maintenance-action ^
--resource-identifier arn:aws:rds:us-east-1:001234567890:cluster:docdb-2025-03-27-19-21-15
```
The result looks similar to this:
```
{
"PendingMaintenanceActions": [
{
"ResourceIdentifier": "arn:aws:rds:us-east-1:001234567890:cluster:docdb-2025-03-27-19-21-15",
"PendingMaintenanceActionDetails": [
{
"Action": "system-update",
"CurrentApplyDate": "2025-04-11T03:01:00Z",
"Description": "db-version-upgrade",
"ForcedApplyDate": "2025-06-18T03:01:00Z",
"AutoAppliedAfterDate": "2025-05-11T03:01:00Z"
"OptInStatus": "pending"
}
]
}
]
}
```
1. If a maintenance action is needed, run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/apply-pending-maintenance-action.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/apply-pending-maintenance-action.html) CLI command with the following options:
+ `--resource-identifier`
+ `--apply-action`
+ `--opt-in-type`
+ `--region`
In the following examples, replace each *user input placeholder* with your cluster's information.
For Linux, macOS, or Unix:
```
aws docdb apply-pending-maintenance-action \
--resource-identifier arn:aws:rds:us-east-1:001234567890:cluster:docdb-2025-03-27-19-21-15 \
--apply-action system-update \
--opt-in-type immediate \
--region us-east-1
```
For Windows:
```
aws docdb apply-pending-maintenance-action ^
--resource-identifier arn:aws:rds:us-east-1:001234567890:cluster:docdb-2025-03-27-19-21-15 ^
--apply-action system-update ^
--opt-in-type immediate ^
--region us-east-1
```
1. Once the maintenance action has completed, run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-pending-maintenance-actions.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-pending-maintenance-actions.html) command again to ensure that there are no other actions pending for your cluster.
The result you want is:
```
{
"PendingMaintenanceActions": []
}
```
------
#### [ Using the Amazon DocumentDB API ]
To unblock a global cluster switchover or failover, you must determine if there are any pending maintenance actions for the cluster and apply them. Use the following APIs to view and apply maintenance actions:
1. Run the following on each secondary region's regional cluster first and then for the primary regions regional cluster.
1. Call the [https://docs.aws.amazon.com/documentdb/latest/developerguide/API_PendingMaintenanceAction.html](https://docs.aws.amazon.com/documentdb/latest/developerguide/API_PendingMaintenanceAction.html) API to determine if any maintenance actions are available for your Amazon DocumentDB global cluster.
1. Apply any changes by calling the [https://docs.aws.amazon.com/documentdb/latest/developerguide/API_ApplyPendingMaintenanceAction.html](https://docs.aws.amazon.com/documentdb/latest/developerguide/API_ApplyPendingMaintenanceAction.html) API.
------