# Managing Amazon DocumentDB clusters
To manage an Amazon DocumentDB cluster, you must have an IAM policy with the appropriate Amazon DocumentDB control plane permissions. These permissions allow you to create, modify, and delete clusters and instances. The `AmazonDocDBFullAccess` policy provides all the required permissions for administering an Amazon DocumentDB cluster.
The following topics show how to perform various tasks when working with Amazon DocumentDB clusters, including creating, deleting, modifying, connecting to, and viewing clusters.
**Topics**
+ [Understanding clusters](db-clusters-understanding.md)
+ [Cluster settings](db-cluster-parameters.md)
+ [Cluster storage configurations](db-cluster-storage-configs.md)
+ [Determining a cluster's status](db-cluster-status.md)
+ [Cluster lifecycle](db-cluster-life-cycle.md)
+ [Scaling clusters](db-cluster-manage-performance.md)
+ [Cloning a volume for a cluster](db-cluster-cloning.md)
+ [Understanding cluster fault tolerance](db-cluster-fault-tolerance.md)
# Understanding clusters
Amazon DocumentDB separates compute and storage, and offloads data replication and backup to the cluster volume. A cluster volume provides a durable, reliable, and highly available storage layer that replicates data six ways across three Availability Zones. Replicas enable higher data availability and read scaling. Each cluster can scale up to 15 replicas.
| Noun | Description | API Operations (Verbs) |
| --- | --- | --- |
| Cluster | Consists of one or more instances and a cluster storage volume that manages the data for those instances. | `create-db-cluster` `delete-db-cluster` `describe-db-clusters` `modify-db-cluster` |
| Instance | Reading and writing data to the cluster storage volume is done via instances. In a given cluster, there are two types of instances: primary and replica. A cluster always has one primary instance and can have 0–15 replicas. | `create-db-instance` `delete-db-instance` `describe-db-instances` `modify-db-instance` `describe-orderable-db-instance-options` `reboot-db-instance` |
| Cluster volume | A virtual database storage volume that spans three Availability Zones, with each Availability Zone having two copies of the cluster data. | N/A |
| Primary instance | Supports both read and write operations, and performs all data modifications to the cluster volume. Each cluster has one primary instance. | N/A |
| Replica instance | Supports only read operations. Each Amazon DocumentDB cluster can have up to 15 replica instances in addition to the primary instance. Multiple replicas distribute the read workload. By locating replicas in separate Availability Zones, you can also increase database availability. | N/A |
| Cluster endpoint | An endpoint for an Amazon DocumentDB cluster that connects to the current primary instance for the cluster. Each Amazon DocumentDB cluster has a cluster endpoint and one primary instance. | N/A |
| Reader endpoint | An endpoint for an Amazon DocumentDB cluster that connects to one of the available replicas for that cluster. Each Amazon DocumentDB cluster has a reader endpoint. If there is more than one replica, the reader endpoint directs each connection request to one of the Amazon DocumentDB replicas. | N/A |
| Instance endpoint | An endpoint for an instance in an Amazon DocumentDB cluster that connects to a specific instance. Each instance in a cluster, regardless of instance type, has its own unique instance endpoint. | N/A |
# Amazon DocumentDB Cluster settings
When you create or modify a cluster, it is important to understand which parameters are immutable and which are modifiable after the cluster has been created. The following table lists all the settings, or parameters, that are specific to a cluster. As specified in the table, some are modifiable, others are not.
**Note**
These settings should not be confused with Amazon DocumentDB cluster parameter groups and their parameters. For more information about cluster parameter groups, see [Managing Amazon DocumentDB cluster parameter groups](cluster_parameter_groups.md).
| Parameter | Modifiable | Notes |
| --- | --- | --- |
| DBClusterIdentifier | Yes | Naming constraints: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/db-cluster-parameters.html) |
| Engine | No | Must be docdb. |
| BackupRetentionPeriod | Yes | Must be between [1-35] days. |
| DBClusterParameterGroupName | Yes | Naming constraints: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/db-cluster-parameters.html) |
| DBSubnetGroupName | No | After a cluster has been created, you cannot modify the cluster's subnet. |
| EngineVersion | No | Value can be 5.0.0 (default), 4.0.0, or 3.6.0. |
| KmsKeyId | No | If you choose to encrypt your cluster, you cannot change the AWS KMS key that you used to encrypt your cluster. |
| MasterUsername | No | After a cluster has been created, you cannot modify the `MasterUsername`. Naming constraints: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/db-cluster-parameters.html) |
| MasterUserPassword | Yes | Constraints: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/db-cluster-parameters.html) |
| Port | Yes | The port number applies to all instances in the cluster. |
| PreferredBackupWindow | Yes | |
| PreferredMaintenanceWindow | Yes | |
| StorageEncrypted | No | If you choose to encrypt your cluster, it cannot be unencrypted. |
| StorageType | Yes | The storage type for the DB cluster: Standard (`standard`) or I/O-Optimized (`iopt1`). Default: `standard` This parameter can be configured with `CreateDBCluster` and `ModifyDBCluster`. For more information, see [Amazon DocumentDB cluster storage configurations](db-cluster-storage-configs.md). |
| Tags | Yes | |
| VpcSecurityGroupIds | No | After a cluster has been created, you cannot modify the VPC that the cluster resides in. |
# Amazon DocumentDB cluster storage configurations
Starting from Amazon DocumentDB 5.0, instance-based clusters support two storage configuration types:
+ **Amazon DocumentDB standard storage**: Designed for customers with low to moderate I/O consumption. If you expect your I/O costs to be less than 25% of your total Amazon DocumentDB cluster, this choice might be ideal for you. With the Amazon DocumentDB standard storage configuration, you’re billed on a pay-per-request I/O basis in addition to instance and storage charges. This means your billing might vary from one cycle to another based on usage. The configuration is tailored to accommodate fluctuating I/O demands of your application.
+ **Amazon DocumentDB I/O-optimized storage**: Designed for customers who prioritize price predictability or have I/O intensive applications. The I/O-optimized configuration offers improved performance, increased throughput, and reduced latency for customers with I/O intensive workloads. If you expect your I/O costs to exceed 25% of your total Amazon DocumentDB cluster costs, this option offers enhanced price performance. With the Amazon DocumentDB I/O-optimized storage configuration, you won't be charged based on I/O operations, ensuring predictable costs each billing cycle. The configuration stabilizes costs while improving performance.
You can switch your existing database clusters once every 30 days to Amazon DocumentDB I/O-optimized storage. You can switch back to Amazon DocumentDB standard storage at any time. The next date to modify the storage configuration to I/O-optimized can be tracked with the `describe-db-clusters` command using the AWS CLI or through the AWS Management Console in the cluster's configuration page.
You can create a new database cluster including the Amazon DocumentDB I/O-optimized configuration or convert your existing database clusters with a few clicks in the [AWS Management Console](https://console.aws.amazon.com/docdb/), a single parameter change in the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), or through [AWS SDKs](https://aws.amazon.com/developer/tools/). There is no downtime or reboot of instances required during or after modifying the storage configuration.
![\[Image: A table describing the differences between Amazon DocumentDB standard and optimized storage.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/io-diagram-1.png)
## Creating an I/O-optimized cluster
------
#### [ Using the AWS Management Console ]
To create or modify an I/O-optimized cluster using the AWS Management Console:
1. On the Amazon DocumentDB management console, under **Clusters**, choose either **Create** or select the cluster and choose **Actions**, and then choose **Modify**.
1. If you are creating a new cluster, make sure you choose **Instance Based Cluster** in the **Cluster type** section (this is the default option).
![\[Image: A console screen capture of the cluster type options.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/create-cluster/cc-type.png)
1. In the **Configuration** section, under **Cluster storage configuration**, choose **Amazon DocumentDB I/O-Optimized**.
![\[Image: A console screen capture of the cluster storage configuration options.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/storage-config-1.png)
1. Complete your cluster creation or modification and choose **Create cluster** or **Modify cluster**.
For the complete Create cluster process, see [Creating a cluster and primary instance using the AWS Management Console](db-cluster-create.md#db-cluster-create-con).
For the complete Modify cluster process, see [Modifying an Amazon DocumentDB cluster](db-cluster-modify.md).
------
#### [ Using the AWS CLI ]
To create an I/O-optimized cluster using the AWS CLI:
In the following examples, replace each *user input placeholder* with your own information.
For Linux, macOS, or Unix:
```
aws docdb create-db-cluster \
--db-cluster-identifier sample-cluster \
--engine docdb \
--engine-version 5.0.0 \
--storage-type iopt1 \
--deletion-protection \
--master-username username \
--master-user-password password
```
For Windows:
```
aws docdb create-db-cluster ^
--db-cluster-identifier sample-cluster ^
--engine docdb ^
--engine-version 5.0.0 ^
--storage-type iopt1 ^
--deletion-protection ^
--master-username username ^
--master-user-password password
```
------
## Cost analysis for determining storage configuration
With Amazon DocumentDB, you have the flexibility to choose your storage configuration for every database cluster you have. In order to properly allocate your clusters between standard and I/O-optimized, you can track your Amazon DocumentDB costs cluster-wise. To do so, you can add tags to existing clusters, enable cost allocation tagging in your [AWS Billing and Cost Management dashboard](https://aws.amazon.com/pricing/), and analyze your costs for a given cluster in the [AWS Cost Explorer Service](https://aws.amazon.com/aws-cost-management/aws-cost-explorer/). For information on cost analysis, see our blog [Using cost allocation tags](https://aws.amazon.com/blogs/database/using-cost-allocation-tags-with-amazon-documentdb-with-mongodb-compatibility/).
# Determining a cluster's status
You can determine a cluster's status using the AWS Management Console or AWS CLI.
------
#### [ Using the AWS Management Console ]
Use the following procedure to see the status of your Amazon DocumentDB cluster using the AWS Management Console
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 **Cluster identifier** column, find the name of the cluster that you are interested in. Then, to find the status of the cluster, read across that row to the **Status** column, as shown below.
![\[Screenshot of clusters page with sample-cluster showing active status.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/db-cluster-status-con.png)
------
#### [ Using the AWS CLI ]
Use the `describe-db-clusters` operation to see the the status of your Amazon DocumentDB cluster using the AWS CLI.
The following code finds the status of the cluster `sample-cluster`.
For Linux, macOS, or Unix:
```
aws docdb describe-db-clusters \
--db-cluster-identifier sample-cluster \
--query 'DBClusters[*].[DBClusterIdentifier,Status]'
```
For Windows:
```
aws docdb describe-db-clusters ^
--db-cluster-identifier sample-cluster ^
--query 'DBClusters[*].[DBClusterIdentifier,Status]'
```
Output from this operation looks something like the following (JSON format).
```
[
[
"sample-cluster",
"available"
]
]
```
------
# Amazon DocumentDB cluster lifecycle
The lifecycle of an Amazon DocumentDB cluster includes creating, describing, modifying, and deleting the cluster. This section provides information about how to complete these processes.
**Topics**
+ [Creating a cluster](db-cluster-create.md)
+ [Describing clusters](db-cluster-view-details.md)
+ [Modifying a cluster](db-cluster-modify.md)
+ [Determining pending maintenance](db-cluster-determine-pending-maintenance.md)
+ [Patch updating a cluster's engine version](db-cluster-version-upgrade.md)
+ [Stopping and starting a cluster](db-cluster-stop-start.md)
+ [Deleting a cluster](db-cluster-delete.md)
# Creating an Amazon DocumentDB cluster
An Amazon DocumentDB cluster consists of instances and a cluster volume that represents the data for the cluster. The cluster volume is replicated six ways across three Availability Zones as a single, virtual volume. The cluster contains a primary instance and, optionally, up to 15 replica instances.
The following sections show how to create an Amazon DocumentDB cluster using either the AWS Management Console or the AWS CLI. You can then add additional replica instances for that cluster. When you use the console to create your Amazon DocumentDB cluster, a primary instance is automatically created for you at the same time. If you use the AWS CLI to create your Amazon DocumentDB cluster, after the cluster's status is *available*, you must then create the primary instance for that cluster.
## Prerequisites
The following are prerequisites for creating an Amazon DocumentDB cluster.
If you do not have an AWS account, complete the following steps to create one.
**To sign up for an AWS account**
1. Open [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup).
1. Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call or text message and entering a verification code on the phone keypad.
When you sign up for an AWS account, an *AWS account root user* is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform [tasks that require root user access](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks).
### VPC prerequisites
You can only create an Amazon DocumentDB cluster in an Amazon Virtual Private Cloud (Amazon VPC). Your Amazon VPC must have at least one subnet in each of at least two Availability Zones in order for you to use it with an Amazon DocumentDB cluster. By distributing your cluster instances across Availability Zones, you ensure that instances are available in your cluster in the unlikely case of an Availability Zone failure.
### Subnet prerequisites
When creating an Amazon DocumentDB cluster, you must choose a VPC and corresponding subnet group within that VPC to launch your cluster. Subnets determine the Availability Zone and IP range within that Availability Zone that you want to use to launch an instance. For the purposes of this discussion, the terms *subnet* and *Availability Zone* are used interchangeably. A subnet group is a named set of subnets (or Availability Zones). What a subnet group allows you to do is specify the Availability Zones that you want to use to for launching Amazon DocumentDB instances. For example, in a cluster with three instances, it is recommended for high availability that each of those instances is provisioned in separate Availability Zones. Thus, if a single Availability Zone goes down, it only affects a single instance.
Amazon DocumentDB instances can currently be provisioned in up to three Availability Zones. Even if a subnet group has more than three subnets, you can only use three of those subnets to create an Amazon DocumentDB cluster. As a result, it is suggested that when you create a subnet group, only choose the three subnets that you want to deploy your instances to. In US East (N. Virginia), your subnet group can have six subnets (or Availability Zones). However, when an Amazon DocumentDB cluster is provisioned, Amazon DocumentDB chooses three of those Availability Zones that it uses to provision instances.
For example, suppose that when you are creating a cluster, Amazon DocumentDB chooses the Availability Zones \$11A, 1B, and 1C\$1. If you try to create an instance in Availability Zone \$11D\$1, the API call fails. However, if you choose to create an instance without specifying a particular Availability Zone, then Amazon DocumentDB chooses an Availability Zone on your behalf. Amazon DocumentDB uses an algorithm to load balance the instances across Availability Zones to help you achieve high availability. For example, if three instances are provisioned, by default, they are provisioned across three Availability Zones and are not provisioned all in a single Availability Zone.
**Recommendations:**
+ Unless you have a specific reason, always create a subnet group with three subnets. Doing so helps ensure that clusters with three or more instances can achieve higher availability as instances are provisioned across three Availability Zones.
+ Always spread instances across multiple Availability Zones to achieve high availability. Never place all instances for a cluster in a single Availability Zone.
+ Because failover events can happen at any time, you should not assume that a primary instance or replica instances are always in a particular Availability Zone.
### Additional prerequisites
The following are some additional prerequisites for creating an Amazon DocumentDB cluster:
+ If you are connecting to AWS using AWS Identity and Access Management (IAM) credentials, your IAM account must have IAM policies that grant the permissions that are required to perform Amazon DocumentDB operations.
If you are using an IAM account to access the Amazon DocumentDB console, you must first sign in to the AWS Management Console with your IAM account. Then go to the Amazon DocumentDB console at [https://console.aws.amazon.com/docdb](https://console.aws.amazon.com/docdb).
+ If you want to tailor the configuration parameters for your cluster, you must specify a cluster parameter group and parameter group with the required parameter settings. For information about creating or modifying a cluster parameter group or parameter group, see [Managing Amazon DocumentDB cluster parameter groups](cluster_parameter_groups.md).
+ You must determine the TCP/IP port number that you want to specify for your cluster. The firewalls at some companies block connections to the default ports for Amazon DocumentDB. If your company firewall blocks the default port, choose another port for your cluster. All instances in a cluster use the same port.
## Creating a cluster and primary instance using the AWS Management Console
The following procedures describe how to use the console to launch an Amazon DocumentDB cluster with one or more instances.
### Create a cluster: using default settings
**To create a cluster with instances using the default settings using the AWS Management Console**
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. If you want to create your cluster in an AWS Region other than the US East (N. Virginia) Region, choose the Region from the list in the upper-right section of the console.
1. In the navigation pane, choose **Clusters**, and then choose **Create**.
**Tip**
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.
1. On the **Create Amazon DocumentDB cluster** page, complete the **Configuration** pane.
1. **Cluster identifier**—Accept the Amazon DocumentDB provided name, or enter a name for your cluster; for example, **sample-cluster**.
Cluster naming constraints:
+ Length is [1—63] letters, numbers, or hyphens.
+ First character must be a letter.
+ Cannot end with a hyphen or contain two consecutive hyphens.
+ Must be unique for all clusters across Amazon RDS, Neptune, and Amazon DocumentDB per AWS account, per Region.
1. **Engine version**—Accept the default engine version of 5.0.0, or optionally choose 8.0.0, 4.0.0, or 3.6.0.
1. **Instance class**—Accept the default `db.r5.large`, or choose the instance class that you want from the list.
1. **Number of instances**—In the list, choose the number of instances that you want to be created with this cluster. The first instance is the primary instance, and all other instances are read-only replica instances. You can add and delete instances later if you need to. By default, an Amazon DocumentDB cluster launches with three instances (one primary and two replicas).
1. Complete the **Cluster storage configuration** section.
Choose either **Amazon DocumentDB Standard** (default) or **Amazon DocumentDB I/O-Optimized**. For more information, see [Amazon DocumentDB cluster storage configurations](db-cluster-storage-configs.md).
1. Complete the **Authentication** pane.
1. **Username**—Enter a name for the primary user. To log in to your cluster, you must use the primary user name.
Primary user naming constraints:
+ Length is [1—63] alphanumeric characters.
+ First character must be a letter.
+ Cannot be a word reserved by the database engine.
1. Choose one of the following password options:
+ **Managed in AWS Secrets Manager**—Choose this option if you want AWS Secrets Manager to automatically manage your primary user password.
If you choose this option, configure the KMS key by either creating your own or using a key that Secrets Manager creates.
+ **Self managed**—Choose this option if you want to self-manage your primary user password. If you choose this option, enter a password for the primary user, and then confirm it. To log in to your cluster, you must use the password for the primary user.
Password constraints:
+ Length is [8-100] printable ASCII characters.
+ Can use any printable ASCII characters except for the following:
+ **/** (forward slash)
+ **"** (double quotation mark)
+ **@** (at symbol)
1. At the bottom of the screen, choose one of the following:
+ To create the cluster now, choose **Create cluster**.
+ To not create the cluster, choose **Cancel**.
+ To further configure the cluster before creating, choose **Show additional configurations**, and then continue at [Create a cluster: additional configurations](#db-cluster-create-con-additional-configs).
The configurations covered in the **Additional Configurations** section are as follows:
+ **Network settings**—The default is to use the `default` VPC security group.
+ **Cluster options**—The default is to use port is 27017 and the default parameter group.
+ **Encryption**—The default is to enable encryption using the `(default) aws/rds` key.
**Important**
After a cluster is encrypted, it cannot be unencrypted.
+ **Backup**—The default is to retain backups for 1 day and let Amazon DocumentDB choose the backup window.
+ **Log exports**—The default is to not export audit logs to CloudWatch Logs.
+ **Maintenance**—The default is to let Amazon DocumentDB choose the maintenance window.
+ **Deletion protection**—Protect your cluster from accidental deletion. Default for cluster created using the console is *enabled*.
If you accept the default settings now, you can change most of them later by modifying the cluster.
1. Enable inbound connection for your cluster's security group.
If you did not change the defaults settings for your cluster, you created a cluster using the default security group for the default VPC in the given region. To connect to Amazon DocumentDB, you must enable inbound connections on port 27017 (or the port of your choice) for your cluster’s security group.
**To add an inbound connection to your cluster's security group**
1. Sign in to the AWS Management Console and open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the **Resources** section of the main window, choose **Security groups**.
![\[Image: Resources list highlighting the Security Groups link option.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-ec2-security-groups.png)
1. From the list of security groups locate the security group you used when creating your cluster (it is most likely the *default* security group) and choose the box to the left of the security group's name.
![\[Image: Security groups list highlighting one security group with box selected.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-ec2-default-sg.png)
1. From the **Actions** menu, choose **Edit inbound rules** then choose or enter the rule constraints.
1. **Type**—From the list, choose the protocol to open to network traffic.
1. **Protocol**—From the list, choose the type of protocol.
1. **Port Range**—For a custom rule, enter a port number or port range. Be sure that the port number or range includes the port you specified when you created your cluster (default: 27017).
1. **Source**—Specifies the traffic that can reach your instance. From the list, choose the traffic source. If you choose **Custom**, specify a single IP address or an IP address range in CIDR notation (e.g., 203.0.113.5/32).
1. **Description**—Enter a description for this rule.
1. When finished creating the rule, choose **Save**.
### Create a cluster: additional configurations
If you want to accept the default settings for your cluster, you can skip the following steps and choose **Create cluster**.
1. Complete the **Network settings** pane.
![\[Screenshot showing the network settings pane and the steps to configure the network settings.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/create-db-cluster-console-network-settings.png)
1. **Virtual Private Cloud (VPC)**—In the list, choose the Amazon VPC that you want to launch this cluster in.
1. **Subnet group**—In the list, choose the subnet group you want to use for this cluster.
1. **VPC security groups**—In the list, choose the VPC security group for this cluster.
1. Complete the **Cluster options** pane.
![\[Screenshot showing the cluster options pane with the steps to configure the cluster settings.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/create-db-cluster-console-cluster-options.png)
1. **Data base port**—Use the up and down arrows to set the TCP/IP port that applications will use to connect to your instance.
1. **Cluster parameter group**—In the list of parameter groups, choose the cluster parameter group for this cluster.
1. Complete the **Encryption** pane.
![\[Screenshot of the encryption pane showing the steps to configure encryption for the cluster.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/encrypt-at-rest.png)
1. **Encryption-at-rest**—Choose one of the following:
+ **Enable encryption**—Default. All data at rest is encrypted. If you choose to encrypt your data, you cannot undo this action.
+ **Disable encryption**—Your data is not encrypted.
1. **AWS KMS key**—This is only available if you are encrypting your data. In the list, choose the key that you want to use for encrypting the data in this cluster. The default is `(default) aws/rds`.
If you chose **Enter a key ARN**, you must enter an Amazon Resource Name (ARN) for the key.
1. Complete the **Backup** pane.
![\[Screenshot of the Backup pane showing the steps to configure the cluster backup window.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/create-db-cluster-console-backup.png)
1. **Backup retention period**—In the list, choose the number of days to keep automatic backups of this cluster before deleting them.
1. **Backup window**—Set the daily time and duration during which Amazon DocumentDB is to make backups of this cluster.
1. **Start time**—In the first list, choose the start time hour (UTC) for starting your automatic backups. In the second list, choose the minute of the hour that you want automatic backups to begin.
1. **Duration**—In the list, choose the number of hours to be allocated to creating automatic backups.
1. Complete the **Log exports** pane by selecting the types of logs you want to export to CloudWatch Logs.
![\[Screenshot of the Log exports pane showing the steps to configure the cluster's DML logging.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/create-db-cluster-console-log-exports.png)
+ **Audit logs**—Select this option to enable exporting audit logs to Amazon CloudWatch Logs. If you select **Audit logs**, you must enable `audit_logs` in the cluster's custom parameter group. For more information, see [Auditing Amazon DocumentDB events](event-auditing.md).
+ **Profiler logs**—Select this option to enable exporting operation profiler logs to Amazon CloudWatch Logs. If you select **Profiler logs**, you must also modify the following parameters in the cluster's custom parameter group:
+ `profiler`—Set to `enabled`.
+ `profiler_threshold_ms`—Set to a value `[0-INT_MAX]` to set the threshold for profiling operations.
+ `profiler_sampling_rate`—Set to a value `[0.0-1.0]` to set the percentage of slow operations to profile.
For more information, see [Profiling Amazon DocumentDB operations](profiling.md).
1. Complete the **Maintenance** pane.
![\[Screenshot of the Maintenance pane showing the steps to configure the cluster's maintenance window.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/create-db-cluster-console-maintenance.png)
1. Choose one of the following
+ **Select window**—You can specify the day of the week, UTC start time, and duration for Amazon DocumentDB to perform maintenance on your cluster.
1. **Start day**—In the list, choose the day of the week to start cluster maintenance.
1. **Start time**—In the lists, choose the hour and minute (UTC) to start maintenance.
1. **Duration**—In the list, choose how much time to allocate for cluster maintenance. If maintenance cannot be finished in the specified time, the maintenance process will continue past the specified time until finished.
+ **No preference**—Amazon DocumentDB chooses the day of the week, start time, and duration for performing maintenance.
1. If you want to add one or more tags to this cluster, complete the **Tags** pane.
![\[Screenshot of the Enable deletion protection checkbox, which is selected.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/create-db-cluster-console-tags.png)
For each tag you want to add to the cluster, repeat the following steps. You may have up to 10 on a cluster.
1. Choose **Add tags**.
1. Type the tag's **Key**.
1. Optionally type the tag's **Value**.
To remove a tag, choose **Remove tag**.
1. **Deletion Protection** is enabled by default when you create a cluster using the console. To disable deletion protection, clear **Enable deletion protection**. When enabled, deletion protection prevents a cluster from being deleted. To delete a deletion protected cluster, you must first modify the cluster to disable deletion protection.
![\[Screenshot of the Enable deletion protection checkbox, which is selected.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/create-db-cluster-console-deletion-protection.png)
For more information about deletion protection, see [Deleting an Amazon DocumentDB cluster](db-cluster-delete.md).
1. To create the cluster, choose **Create cluster**. Otherwise, choose **Cancel**.
## Creating a cluster using the AWS CLI
The following procedures describe how to use the AWS CLI to launch an Amazon DocumentDB cluster and create an Amazon DocumentDB replica.
**Parameters**
+ **--db-cluster-identifier**—Required. A lowercase string that identifies this cluster.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/db-cluster-create.html)
+ **--engine**—Required. Must be **docdb**.
+ **--deletion-protection \$1 --no-deletion-protection**—Optional. When deletion protection is enabled, it prevents a cluster from being deleted. When you use the AWS CLI, the default setting is to have deletion protection disabled.
For more information about deletion protection, see [Deleting an Amazon DocumentDB cluster](db-cluster-delete.md).
+ **--storage-type standard \$1 iopt1**—Optional. Default: **standard**. The cluster's storage configuration. Valid values are `standard` (Standard) or `iopt1` (I/O-optimized).
+ **--master-username**—Required. The user name used to authenticate the user.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/db-cluster-create.html)
+ **--master-user-password**—Optional. The user's password used to authenticate the user.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/db-cluster-create.html)
+ **--manage-master-user-password**—Optional. Amazon DocumentDB generates the master user password and manages it throughout its lifecycle in Secrets Manager.
For additional parameters, see [CreateDBCluster](API_CreateDBCluster.md).
**To launch an Amazon DocumentDB cluster using the AWS CLI**
To create an Amazon DocumentDB cluster, call the `create-db-cluster` AWS CLI. The following AWS CLI command creates an Amazon DocumentDB cluster named `sample-cluster` with deletion protection enabled. 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). 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.
**Note**
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.
For Linux, macOS, or Unix:
```
aws docdb create-db-cluster \
--db-cluster-identifier sample-cluster \
--engine docdb \
--engine-version 5.0.0 \
--deletion-protection \
--master-username masteruser \
--master-user-password password
```
For Windows:
```
aws docdb create-db-cluster ^
--db-cluster-identifier sample-cluster ^
--engine docdb ^
--engine-version 5.0.0 ^
--deletion-protection ^
--master-username masteruser ^
--master-user-password password
```
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": "5.0.0",
"MasterUsername": "masteruser",
"BackupRetentionPeriod": 1,
"DBClusterArn": "arn:aws:rds:us-east-1:123456789012:cluster:sample-cluster",
"DBClusterIdentifier": "sample-cluster",
"MultiAZ": false,
"DBClusterParameterGroup": "default.docdb5.0",
"PreferredBackupWindow": "09:12-09:42",
"DbClusterResourceId": "cluster-KQSGI4MHU4NTDDRVNLNTU7XVAY",
"PreferredMaintenanceWindow": "tue:04:17-tue:04:47",
"Port": 27017,
"Status": "creating",
"ReaderEndpoint": "sample-cluster.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": "sample-cluster.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 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).
For more information, see [https://docs.aws.amazon.com/documentdb/latest/developerguide/API_CreateDBCluster.html](https://docs.aws.amazon.com/documentdb/latest/developerguide/API_CreateDBCluster.html) in the *Amazon DocumentDB API Reference*.
# Describing Amazon DocumentDB clusters
You can use either Amazon DocumentDB Management Console or the AWS CLI to see details such as connection endpoints, security groups, VPCs, and parameter groups pertaining to your Amazon DocumentDB clusters.
For more information, see the following:
+ [Monitoring an Amazon DocumentDB cluster's status](monitoring_docdb-cluster_status.md)
+ [Finding a cluster's endpoints](db-cluster-endpoints-find.md)
------
#### [ Using the AWS Management Console ]
Use the following procedure to view the details of a specified Amazon DocumentDB cluster using the console.
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**.
**Tip**
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.
1. In the list of clusters, choose the name of the cluster that you want to see the details of. The information about the cluster is organized into the following groupings:
+ **Summary** — General information about the cluster, including the engine version, cluster status, pending maintenance, and the status of its parameter group.
+ **Connectivity & Security** —The **Connect** section lists connection endpoints to connect to this cluster with the mongo shell or with an application. The **Security Groups** section lists the security groups associated with this cluster and their VPC ID and descriptions.
+ **Configuration** — The **Cluster details** section lists details about the cluster, including the cluster's Amazon Resource Name (ARN), endpoint, and parameter group. It also lists the cluster's backup information, maintenance details, and security and network settings. The **Cluster instances** section lists the instances that belong to this cluster with each instance's role and cluster parameter group status.
+ **Monitoring** — The Amazon CloudWatch Logs metrics for this cluster. For more information, see [Monitoring Amazon DocumentDB with CloudWatch](cloud_watch.md).
+ **Events & tags** — The **Recent events** section lists the recent events for this cluster. Amazon DocumentDB keeps a record of events that relate to your clusters, instances, snapshots, security groups, and cluster parameter groups. This information includes the date, time, and message associated with each event. The **Tags** section lists the tags attached to this cluster.
------
#### [ Using the AWS CLI ]
To view the details of your Amazon DocumentDB clusters using the AWS CLI, use the `describe-db-clusters` command as shown in the examples below. For more information, see [https://docs.aws.amazon.com/documentdb/latest/developerguide/API_DescribeDBClusters.html](https://docs.aws.amazon.com/documentdb/latest/developerguide/API_DescribeDBClusters.html) in the *Amazon DocumentDB Resource Management API Reference*.
**Note**
For certain management features such as cluster and instance lifecycle management, Amazon DocumentDB leverages operational technology that is shared with Amazon RDS. The `filterName=engine,Values=docdb` filter parameter returns only Amazon DocumentDB clusters.
**Example**
**Example 1: List all Amazon DocumentDB clusters **
The following AWS CLI code lists the details for all Amazon DocumentDB clusters in a region.
```
aws docdb describe-db-clusters --filter Name=engine,Values=docdb
```
Output from this operation looks something like the following.
```
{
"DBClusters": [
{
"AvailabilityZones": [
"us-east-1c",
"us-east-1b",
"us-east-1a"
],
"BackupRetentionPeriod": 1,
"DBClusterIdentifier": "sample-cluster-1",
"DBClusterParameterGroup": "sample-parameter-group",
"DBSubnetGroup": "default",
"Status": "available",
...
},
{
"AvailabilityZones": [
"us-east-1c",
"us-east-1b",
"us-east-1a"
],
"BackupRetentionPeriod": 1,
"DBClusterIdentifier": "sample-cluster-2",
"DBClusterParameterGroup": "sample-parameter-group",
"DBSubnetGroup": "default",
"Status": "available",
...
},
{
"AvailabilityZones": [
"us-east-1c",
"us-east-1b",
"us-east-1a"
],
"BackupRetentionPeriod": 1,
"DBClusterIdentifier": "sample-cluster-3",
"DBClusterParameterGroup": "sample-parameter-group",
"DBSubnetGroup": "default",
"Status": "available",
...
}
]
}
```
**Example**
**Example 2: List all details for a specified Amazon DocumentDB cluster**
The following AWS CLI code lists the details for the cluster `sample-cluster`.
For Linux, macOS, or Unix:
```
aws docdb describe-db-clusters \
--filter Name=engine,Values=docdb \
--db-cluster-identifier sample-cluster
```
For Windows:
```
aws docdb describe-db-clusters ^
--filter Name=engine,Values=docdb ^
--db-cluster-identifier sample-cluster
```
Output from this operation looks something like the following.
```
{
"DBClusters": [
{
"AllocatedStorage": 1,
"AvailabilityZones": [
"us-east-1c",
"us-east-1a",
"us-east-1d"
],
"BackupRetentionPeriod": 2,
"DBClusterIdentifier": "sample-cluster",
"DBClusterParameterGroup": "sample-parameter-group",
"DBSubnetGroup": "default",
"Status": "available",
"EarliestRestorableTime": "2023-11-07T22:34:08.148000+00:00",
"Endpoint": "sample-cluster.node.us-east-1.amazon.com",
"ReaderEndpoint": "sample-cluster.node.us-east-1.amazon.com",
"MultiAZ": false,
"Engine": "docdb",
"EngineVersion": "5.0.0",
"LatestRestorableTime": "2023-11-10T07:21:16.772000+00:00",
"Port": 27017,
"MasterUsername": "chimeraAdmin",
"PreferredBackupWindow": "22:22-22:52",
"PreferredMaintenanceWindow": "sun:03:01-sun:03:31",
"ReadReplicaIdentifiers": [],
"DBClusterMembers": [
{
"DBInstanceIdentifier": "sample-instance-1",
"IsClusterWriter": true,
"DBClusterParameterGroupStatus": "in-sync",
"PromotionTier": 1
},
{
"DBInstanceIdentifier": "sample-instance-2",
"IsClusterWriter": true,
"DBClusterParameterGroupStatus": "in-sync",
"PromotionTier": 1
},
],
"VpcSecurityGroups": [
{
"VpcSecurityGroupId": "sg-9084c2ec",
"Status": "active"
}
],
"HostedZoneId": "Z06853723JYKYBXTJ49RB",
"StorageEncrypted": false,
"DbClusterResourceId": "cluster-T4LGLANHVAPGQYYULWUDKLVQL4",
"DBClusterArn": "arn:aws:rds:us-east-1:123456789012:cluster:sample-cluster",
"AssociatedRoles": [],
"IAMDatabaseAuthenticationEnabled": false,
"ClusterCreateTime": "2023-11-06T18:05:41.568000+00:00",
"EngineMode": "provisioned",
"DeletionProtection": false,
"HttpEndpointEnabled": false,
"CopyTagsToSnapshot": false,
"CrossAccountClone": false,
"DomainMemberships": [],
"TagList": [],
"StorageType": "iopt1",
"AutoMinorVersionUpgrade": false,
"NetworkType": "IPV4",
"IOOptimizedNextAllowedModificationTime": "2023-12-07T18:05:41.580000+00:00"
}
]
}
```
**Example**
**Example 3: List specific details for a Amazon DocumentDB cluster**
To list a subset of the clusters' details using the AWS CLI, add a `--query` that specifies which cluster members the `describe-db-clusters` operation is to list. The `--db-cluster-identifier` parameter is the identifier for the particular cluster that you want to display the details of. For more information on queries, see [ How to Filter the Output with the `--query` Option](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-output.html#controlling-output-filter) in the *AWS Command Line Interface User Guide*.
The following example lists the instances in an Amazon DocumentDB cluster.
For Linux, macOS, or Unix:
```
aws docdb describe-db-clusters \
--filter Name=engine,Values=docdb \
--db-cluster-identifier sample-cluster \
--query 'DBClusters[*].[DBClusterMembers]'
```
For Windows:
```
aws docdb describe-db-clusters ^
--filter Name=engine,Values=docdb ^
--db-cluster-identifier sample-cluster ^
--query 'DBClusters[*].[DBClusterMembers]'
```
Output from this operation looks something like the following.
```
[
[
[
{
"DBInstanceIdentifier": "sample-instance-1",
"IsClusterWriter": true,
"DBClusterParameterGroupStatus": "in-sync",
"PromotionTier": 1
},
{
"DBInstanceIdentifier": "sample-instance-2",
"IsClusterWriter": false,
"DBClusterParameterGroupStatus": "in-sync",
"PromotionTier": 1
}
]
]
]
```
------
# Modifying an Amazon DocumentDB cluster
To modify a cluster, the cluster must be in the *available* state. You cannot modify a cluster that is stopped. If the cluster is stopped, first start the cluster, wait for the cluster to become *available*, and then make the desired modifications. For more information, see [Stopping and starting an Amazon DocumentDB cluster](db-cluster-stop-start.md).
------
#### [ Using the AWS Management Console ]
Use the following procedure to modify a specific Amazon DocumentDB cluster using the console.
**To modify an Amazon DocumentDB 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**.
**Tip**
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.
1. Specify the cluster that you want to modify by choosing the button to the left of the cluster's name.
1. Choose **Actions**, and then choose **Modify**.
1. In the **Modify Cluster: ** pane, make the changes that you want. You can make changes in the following areas:
+ **Cluster specifications**—The cluster's name, security groups, and credentials management.
+ **Cluster storage configuration**—The cluster's data storage mode. Choose between Standard and I/O-Optimized configuration.
+ **Cluster options**—The cluster's port and parameter group.
+ **Backup**—The cluster's backup retention period and backup window.
+ **Log exports**—Enable or disable exporting audit or profiler logs.
+ **Maintenance**—Set the cluster's maintenance window.
+ **Deletion protection**—Enable or disable deletion protection on the cluster. Deletion protection is enabled by default.
1. When you're finished, choose **Continue** to view a summary of your changes.
1. If you are satisfied with your changes, you can choose **Modify cluster** to modify your cluster. Alternatively, you can choose **Back** or **Cancel** to edit or cancel your changes, respectively.
It takes a few minutes for your changes to be applied. You can use the cluster only when its status is *available*. You can monitor the cluster's status using the console or AWS CLI. For more information, see [Monitoring an Amazon DocumentDB cluster's status](monitoring_docdb-cluster_status.md).
------
#### [ Using the AWS CLI ]
Use the `modify-db-cluster` operation to modify the specified cluster using the AWS CLI. For more information, see [https://docs.aws.amazon.com/documentdb/latest/developerguide/API_ModifyDBCluster.html](https://docs.aws.amazon.com/documentdb/latest/developerguide/API_ModifyDBCluster.html) in the *Amazon DocumentDB API Reference*.
**Parameters**
+ **--db-cluster-identifier**—Required. The identifier of the Amazon DocumentDB cluster that you are going to modify.
+ **--backup-retention-period**—Optional. The number of days for which automated backups are retained. Valid values are 1–35.
+ **--storage-type**—Optional. The cluster's storage configuration. Valid values are `standard` (Standard) or `iopt1` (I/O-optimized).
+ **--db-cluster-parameter-group-name**—Optional. The name of the cluster parameter group to use for the cluster.
+ **--manage-master-user-password**—Optional. Amazon DocumentDB generates the master user password and manages it throughout its lifecycle in Secrets Manager.
+ **--rotate-master-user-password**—Optional. Secrets Manager generates a new secret version for the existing secret. The new version of the secret contains the new primary user password. Amazon DocumentDB changes the primary user password for the cluster to match the password for the new secret version.
You must specify the **--apply-immediately** option when you rotate the primary password.
+ **--master-user-password**—Optional. The new password for the primary database user.
Password constraints:
+ Length is [8—100] printable ASCII characters.
+ Can use any printable ASCII characters except for the following:
+ **/** (forward slash)
+ **"** (double quotation mark)
+ **@** (at symbol)
+ **--new-db-cluster-identifier**—Optional. The new cluster identifier for the cluster when renaming a cluster. This value is stored as a lowercase string.
Naming constraints:
+ Length is [1—63] letters, numbers, or hyphens.
+ First character must be a letter.
+ Cannot end with a hyphen or contain two consecutive hyphens.
+ Must be unique for all clusters across Amazon RDS, Amazon Neptune, and Amazon DocumentDB per AWS account, per region.
+ **--preferred-backup-window**—Optional. The daily time range during which automated backups are created, in Universal Coordinated Time (UTC).
+ Format: `hh24:mm-hh24:mm`
+ **--preferred-maintenance-window**—Optional. The weekly time range during which system maintenance can occur, in UTC.
+ Format: `ddd:hh24:mm-ddd:hh24:mm`
+ Valid days: `Sun`, `Mon`, `Tue`, `Wed`, `Thu`, `Fri`, and `Sat`.
+ **--deletion-protection** or **--no-deletion-protection**—Optional. Whether deletion protection should be enabled on this cluster. Deletion protection prevents a cluster from being accidentally deleted until the cluster is modified to disable deletion protection. For more information, see [Deleting an Amazon DocumentDB cluster](db-cluster-delete.md).
+ **--apply-immediately** or **--no-apply-immediately**—Use `--apply-immediately` to make the change immediately. Use `--no-apply-immediately` to make the change during your cluster's next maintenance window.
**Example**
The following code changes the backup retention period for the cluster `sample-cluster`.
For Linux, macOS, or Unix:
```
aws docdb modify-db-cluster \
--db-cluster-identifier sample-cluster \
--apply-immediately \
--backup-retention-period 7
```
For Windows:
```
aws docdb modify-db-cluster ^
--db-cluster-identifier sample-cluster ^
--apply-immediately ^
--backup-retention-period 7
```
Output from this operation looks something like the following.
```
{
"DBCluster": {
"BackupRetentionPeriod": 7,
"DbClusterResourceId": "cluster-VDP53QEWST7YHM36TTXOPJT5YE",
"Status": "available",
"DBClusterMembers": [
{
"PromotionTier": 1,
"DBClusterParameterGroupStatus": "in-sync",
"DBInstanceIdentifier": "sample-cluster-instance",
"IsClusterWriter": true
}
],
"ReadReplicaIdentifiers": [],
"AvailabilityZones": [
"us-east-1b",
"us-east-1c",
"us-east-1a"
],
"ReaderEndpoint": "sample-cluster.cluster-ro-ctevjxdlur57.us-east-1.rds.amazonaws.com",
"DBClusterArn": "arn:aws:rds:us-east-1:123456789012:cluster:sample-cluster",
"PreferredMaintenanceWindow": "sat:09:51-sat:10:21",
"EarliestRestorableTime": "2018-06-17T00:06:19.374Z",
"StorageEncrypted": false,
"MultiAZ": false,
"AssociatedRoles": [],
"MasterUsername": "",
"DBClusterIdentifier": "sample-cluster",
"VpcSecurityGroups": [
{
"Status": "active",
"VpcSecurityGroupId": "sg-77186e0d"
}
],
"HostedZoneId": "Z2SUY0A1719RZT",
"LatestRestorableTime": "2018-06-18T21:17:05.737Z",
"AllocatedStorage": 1,
"Port": 27017,
"Engine": "docdb",
"DBClusterParameterGroup": "default.docdb3.4",
"Endpoint": "sample-cluster.cluster-ctevjxdlur57.us-east-1.rds.amazonaws.com",
"DBSubnetGroup": "default",
"PreferredBackupWindow": "00:00-00:30",
"EngineVersion": "3.4",
"ClusterCreateTime": "2018-06-06T19:25:47.991Z",
"IAMDatabaseAuthenticationEnabled": false
}
}
```
It takes a few minutes for your changes to be applied. You can use the cluster only when its status is *available*. You can monitor the cluster's status using the console or AWS CLI. For more information, see [Monitoring an Amazon DocumentDB cluster's status](monitoring_docdb-cluster_status.md).
------
# Determining pending maintenance
You can determine whether you have the latest Amazon DocumentDB engine version by determining whether you have pending cluster maintenance.
------
#### [ Using the AWS Management Console ]
You can use the AWS Management Console to determine whether a cluster has pending maintenance.
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**.
**Tip**
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.
1. Locate the **Maintenance** column to determine whether a cluster has pending maintenance.
![\[Console screenshot showing Amazon DocumentDB cluster maintenance field.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-cluster-pending-maintenance.png)
**None** indicates that the cluster is running the latest engine version. **Available** indicates that the cluster has pending maintenance, which might mean that an engine upgrade is needed.
1. If your cluster has pending maintenance, continue with the steps at [Performing a patch update to a cluster's engine version](db-cluster-version-upgrade.md).
------
#### [ Using the AWS CLI ]
You can use the AWS CLI to determine whether a cluster has the latest engine version by using the `describe-pending-maintenance-actions` operation with the following parameters.
**Parameters**
+ **--resource-identifier**—Optional. The ARN for the resource (cluster). If this parameter is omitted, pending maintenance actions for all clusters are listed.
+ **--region**—Optional. The AWS Region that you want to run this operation in, for example, `us-east-1`.
**Example**
For Linux, macOS, or Unix:
```
aws docdb describe-pending-maintenance-actions \
--resource-identifier arn:aws:rds:us-east-1:123456789012:cluster:sample-cluster \
--region us-east-1
```
For Windows:
```
aws docdb describe-pending-maintenance-actions ^
--resource-identifier arn:aws:rds:us-east-1:123456789012:cluster:sample-cluster ^
--region us-east-1
```
Output from this operation looks something like the following.
```
{
"PendingMaintenanceActions": [
{
"ResourceIdentifier": "arn:aws:rds:us-east-1:123456789012:cluster:sample-cluster",
"PendingMaintenanceActionDetails": [
{
"Description": "New feature",
"Action": "db-upgrade",
"ForcedApplyDate": "2019-02-25T21:46:00Z",
"AutoAppliedAfterDate": "2019-02-25T07:41:00Z",
"CurrentApplyDate": "2019-02-25T07:41:00Z"
}
]
}
]
}
```
If your cluster has pending maintenance, continue with the steps at [Performing a patch update to a cluster's engine version](db-cluster-version-upgrade.md).
------
# Performing a patch update to a cluster's engine version
In this section, we will explain how to deploy a patch update using the AWS Management Console or the AWS CLI. A patch update is an update within the same engine version (for example, updating a 3.6 engine version to a newer 3.6 engine version). You can update it immediately or during your cluster's next maintenance window. To determine whether your engine needs an update, see [Determining pending maintenance](db-cluster-determine-pending-maintenance.md). Please note that when you apply the update, your cluster will experience some downtime.
**Note**
If you are trying to upgrade from a major engine version to another, such as 3.6 to 5.0, see either [Amazon DocumentDB in-place major version upgrade](docdb-mvu.md) or [Upgrading your Amazon DocumentDB cluster using AWS Database Migration Service](docdb-migration.versions.md). An in-place major version upgrade only supports docdb 5.0 as the target engine version.
There are two configuration requirements to get the latest patch updates for a cluster's engine version:
+ The cluster's status must be *available*.
+ The cluster must be running an earlier engine version.
------
#### [ Using the AWS Management Console ]
The following procedure applies patch updates to your cluster's engine version using the console. You have the option to update immediately or during your cluster's next maintenance window.
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**. In the list of clusters, choose the button to the left of the cluster that you want to upgrade. The status of the cluster must be *available*.
**Tip**
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.
1. From the **Actions** menu, choose one of the following options. These menu options are selectable only if the cluster you chose is not running the latest engine version.
![\[Image: Amazon DocumentDB Upgrade actions\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-upgrade-action.png)
+ **Upgrade now**—Immediately initiates the upgrade process. Your cluster will be offline for a time while the cluster is upgraded to the latest engine version.
+ **Upgrade at next window**—Initiates the upgrade process during the cluster's next maintenance window. Your cluster will be offline for a time while it is upgraded to the latest engine version.
1. When the confirmation window opens, choose one of the following:
+ **Upgrade**—To upgrade your cluster to the latest engine version according to the schedule chosen in the previous step.
+ **Cancel**—To cancel the cluster's engine upgrade and continue with the cluster's current engine version.
------
#### [ Using the AWS CLI ]
You can apply patch updates to your cluster using the AWS CLI and the `apply-pending-maintenance-action` operation with the following parameters.
**Parameters**
+ **--resource-identifier**—Required. The ARN of the Amazon DocumentDB cluster that you are going to upgrade.
+ **--apply-action**—Required. The following values are permitted. To upgrade your cluster engine version, use `db-upgrade`.
+ **db-upgrade**
+ **system-update**
+ **--opt-in-type**—Required. The following values are permitted.
+ `immediate`—Apply the maintenance action immediately.
+ `next-maintenance`—Apply the maintenance action during the next maintenance window.
+ `undo-opt-in`—Cancel any existing `next-maintenance` opt-in requests.
**Example**
The following example patch updates the engine version of `sample-cluster` to version 4.0.0.
For Linux, macOS, or Unix:
```
aws docdb apply-pending-maintenance-action \
--resource-identifier arn:aws:rds:us-east-1:123456789012\:cluster:sample-cluster \
--apply-action db-upgrade \
--opt-in-type immediate
```
For Windows:
```
aws docdb apply-pending-maintenance-action ^
--resource-identifier arn:aws:rds:us-east-1:123456789012:cluster:sample-cluster ^
--apply-action db-upgrade ^
--opt-in-type immediate
```
Output from this operation looks like the following.
```
{
"ResourcePendingMaintenanceActions": {
"ResourceIdentifier": "arn:aws:rds:us-east-1:444455556666:cluster:docdb-2019-01-09-23-55-38",
"PendingMaintenanceActionDetails": [
{
"CurrentApplyDate": "2019-02-20T20:57:06.904Z",
"Description": "Bug fixes",
"ForcedApplyDate": "2019-02-25T21:46:00Z",
"OptInStatus": "immediate",
"Action": "db-upgrade",
"AutoAppliedAfterDate": "2019-02-25T07:41:00Z"
}
]
}
}
```
------
# Stopping and starting an Amazon DocumentDB cluster
Stopping and starting Amazon DocumentDB clusters can help you manage costs for development and test environments. Instead of creating and deleting clusters and instances each time you use Amazon DocumentDB, you can temporarily stop all the instances in your cluster when they aren't needed. You can then start them again when you resume your testing.
**Topics**
+ [Overview of stopping and starting a cluster](#db-cluster-stop-start-overview)
+ [Operations you can perform on a stopped cluster](#db-cluster-stopped-operations)
## Overview of stopping and starting a cluster
During periods where you don't need an Amazon DocumentDB cluster, you can stop all instances in that cluster at once. You can then start the cluster again anytime you need to use it. Starting and stopping simplifies the setup and teardown processes for clusters that are used for development, testing, or similar activities that don't require continuous availability. You can stop and start a cluster using the AWS Management Console or the AWS CLI with a single action, regardless of how many instances are in the cluster.
While your cluster is stopped, the cluster storage volume remains unchanged. You are charged only for storage, manual snapshots, and automated backup storage within your specified retention window. You aren't charged for any instance hours. Amazon DocumentDB automatically starts your cluster after seven days so that it doesn't fall behind any required maintenance updates. When your cluster starts after seven days, you will begin to be charged for the instances in the cluster again. While your cluster is stopped, you can't query your storage volume because querying requires that instances are in the available state.
When an Amazon DocumentDB cluster is stopped, neither the cluster nor its instances can be modified in any way. This includes adding or removing instances, or deleting the cluster.
------
#### [ Using the AWS Management Console ]
The following procedure shows you how to stop a cluster with one or more instances in the available state, or start a stopped cluster.
**To stop or start an Amazon DocumentDB 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**.
**Tip**
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.
1. In the list of clusters, choose the button to the left of the name of the cluster that you want to stop or start.
1. Choose **Actions**, and then choose the action that you want to perform on the cluster.
+ If you want to stop the cluster and the cluster is available:
1. Choose **Stop**.
![\[Image: Stop a cluster\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/db-cluster-stop.png)
To avoid activating the failover mechanism, the stop operation stops the replica instances first, and then the primary instance.
1. On the confirmation dialog, confirm that you want to stop the cluster by choosing **Stop cluster**, or to keep the cluster running, choose **Cancel**.
![\[Image: Start a cluster\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/db-cluster-stop-confirm.png)
+ If you want to start the cluster, and the cluster is stopped, choose **Start**.
![\[Image: Start a cluster\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/db-cluster-start.png)
1. Monitor the status of the cluster and its instances. If you started the cluster, you can resume using the cluster when the cluster and its instances are *available*. For more information, see [Determining a cluster's status](db-cluster-status.md).
![\[Image: Status of clusters stopping and starting\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/db-cluster-stop-start-status.png)
------
#### [ Using the AWS CLI ]
The following code examples show you how to stop a cluster with one or more instances in the available state, or start a stopped cluster.
To stop a cluster with one or more available instances using the AWS CLI, use the `stop-db-cluster` operation. To start a stopped cluster, use the `start-db-cluster` operation. Both operations use the `--db-cluster-identifier` parameter.
**Parameter:**
+ **--db-cluster-identifier**—Required. The name of the cluster to stop or start.
**Example — To stop a cluster using the AWS CLI**
The following code stops the cluster `sample-cluster`. The cluster must have one or more instances in the available state.
For Linux, macOS, or Unix:
```
aws docdb stop-db-cluster \
--db-cluster-identifier sample-cluster
```
For Windows:
```
aws docdb stop-db-cluster ^
--db-cluster-identifier sample-cluster
```
**Example — To start a cluster using the AWS CLI**
The following code starts the cluster `sample-cluster`. The cluster must currently be stopped.
For Linux, macOS, or Unix:
```
aws docdb start-db-cluster \
--db-cluster-identifier sample-cluster
```
For Windows:
```
aws docdb start-db-cluster ^
--db-cluster-identifier sample-cluster
```
------
## Operations you can perform on a stopped cluster
While an Amazon DocumentDB cluster is stopped, you can do a point-in-time restore to any point within your specified automated backup retention window. For details about doing a point-in-time restore, see [Restoring to a point in time](backup_restore-point_in_time_recovery.md).
You can't modify the configuration of an Amazon DocumentDB cluster, or any of its instances, while the cluster is stopped. You also can't add or remove instances from the cluster, or delete the cluster if it still has any associated instances. You must start the cluster before performing any such administrative actions.
Amazon DocumentDB applies any scheduled maintenance to your stopped cluster only after it's started again. After seven days, Amazon DocumentDB automatically starts a stopped cluster so that it doesn't fall too far behind in its maintenance status. When the cluster restarts, you will begin to be charged for the instances in the cluster again.
While a cluster is stopped, Amazon DocumentDB does not perform any automated backups nor does it extend the backup retention period.
# Deleting an Amazon DocumentDB cluster
You can delete an Amazon DocumentDB cluster using the AWS Management Console or the AWS CLI. To delete a cluster, the cluster must be in the *available* state and must not have any instances associated with it. If the cluster is stopped, first start the cluster, wait for the cluster to become *available*, and then delete the cluster. For more information, see [Stopping and starting an Amazon DocumentDB cluster](db-cluster-stop-start.md).
## Deletion protection
To protect your cluster from accidental deletion, you can enable *deletion protection*. Deletion protection is enabled by default when you create a cluster using the console. However, deletion protection is disabled by default if you create a cluster using the AWS CLI.
Amazon DocumentDB enforces deletion protection for a cluster whether you perform the delete operation using the console or the AWS CLI. If deletion protection is enabled, you can't delete a cluster. To delete a cluster that has deletion protection enabled, you must first modify the cluster and disable deletion protection.
When using the console with deletion protection enabled on a cluster, you can't delete the cluster's last instance because doing so also deletes the cluster. You can delete the last instance of a deletion protected cluster using the AWS CLI. However, the cluster itself still exists, and your data is preserved. You can access the data by creating new instances for the cluster. For more information about enabling and disabling deletion protection, see:
+ [Creating an Amazon DocumentDB cluster](db-cluster-create.md)
+ [Modifying an Amazon DocumentDB cluster](db-cluster-modify.md)
------
#### [ Using the AWS Management Console ]
To delete a cluster using the AWS Management Console, deletion protection must be disabled.
**To determine whether a cluster has deletion protection enabled:**
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**.
**Tip**
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.
1. Note that in the Clusters navigation box, the **Cluster identifier** column shows both clusters and instances. Instances are listed underneath clusters, similar to the screenshot below.
![\[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/clusters.png)
1. Choose the cluster's name, and select the **Configuration** tab. In the **Cluster details** section, locate **Deletion protection**. If deletion protection is enabled, modify the cluster to disable deletion protection. For information about modifying a cluster, see [Modifying an Amazon DocumentDB cluster](db-cluster-modify.md).
After **Deletion protection** is disabled, you are ready to delete the cluster.
**To delete a cluster:**
1. In the navigation pane, choose **Clusters**.
1. Determine whether the cluster has any instances by checking the **Cluster identifier** column for instances listed below it. Before you can delete a cluster, you must delete all of its instances. For more information, see [Deleting an Amazon DocumentDB instance](db-instance-delete.md).
1. Depending on whether your cluster has any instances, do one of the following steps.
+ If the cluster has no instances, select the button to the left of the cluster name and choose **Actions**. From the dropdown menu, choose **Delete**. Complete the **Delete ** dialog box, and then choose **Delete**.
+ If the cluster has one or more instances, do the following:
1. In the navigation pane, choose **Clusters**.
1. Delete each of the cluster's instances by selecting the checkbox to the left of the cluster's name. Select **Actions**, and then choose **Delete**. Complete the **Delete ** dialog box, and then choose **Delete**.
When you delete the last instance, the cluster will also be deleted. For more information about deleting instances, see [Deleting an Amazon DocumentDB instance](db-instance-delete.md).
It takes several minutes for the cluster to be deleted. To monitor the status of the cluster, see [Monitoring an Amazon DocumentDB cluster's status](monitoring_docdb-cluster_status.md).
------
#### [ Using the AWS CLI ]
You cannot delete a cluster that has any instances associated with it. To determine which instances are associated with your cluster, run the `describe-db-clusters` command and delete all of the cluster's instances. Then, if needed, disable deletion protection on your cluster, and finally, delete the cluster.
1. **First, delete all of the cluster's instances.**
To determine which instances you need to delete, run the following command.
```
aws docdb describe-db-clusters \
--db-cluster-identifier sample-cluster \
--query 'DBClusters[*].[DBClusterIdentifier,DBClusterMembers[*].DBInstanceIdentifier]'
```
Output from this operation looks something like the following (JSON format).
```
[
[
"sample-cluster",
[
"sample-instance-1",
"sample-instance-2"
]
]
]
```
If the cluster you want to delete has any instances, delete them as shown below.
```
aws docdb delete-db-instance \
--db-instance-identifier sample-instance
```
1. **Second, disable deletion protection.**
Using the AWS CLI to delete all of a cluster's instances does not delete the cluster. You must also delete the cluster, but you can do this only if deletion protection is disabled.
To determine whether the cluster has deletion protection enabled, run the following command.
**Tip**
To see the deletion protection status of all your Amazon DocumentDB clusters, omit the `--db-cluster-identifier` parameter.
```
aws docdb describe-db-clusters \
--db-cluster-identifier sample-cluster \
--query 'DBClusters[*].[DBClusterIdentifier,DeletionProtection]'
```
Output from this operation looks something like the following.
```
[
[
"sample-cluster",
"true"
]
]
```
If the cluster has deletion protection enabled, modify the cluster and disable deletion protection. To disable deletion protection on the cluster, run the following command.
```
aws docdb modify-db-cluster \
--db-cluster-identifier sample-cluster \
--no-deletion-protection \
--apply-immediately
```
1. **Finally, delete the cluster.**
After deletion protection is disabled, you are ready to delete the cluster. To delete a cluster, use the `delete-db-cluster` operation with the following parameters.
+ **--db-cluster-identifier**—Required. The identifier of the cluster that you want to delete.
+ **--final-db-snapshot-identifier**—Optional. If you want a final snapshot, you must include this parameter with a name for the final snapshot. You must include either `--final-db-snapshot-identifier` or `--skip-final-snapshot`.
Naming constraints:
+ Length is [1—63] letters, numbers, or hyphens.
+ First character must be a letter.
+ Cannot end with a hyphen or contain two consecutive hyphens.
+ Must be unique for all clusters across Amazon RDS, Amazon Neptune, and Amazon DocumentDB per AWS account, per Region.
+ **--skip-final-snapshot**—Optional. Use this parameter only if you don't want to take a final snapshot before deleting your cluster. The default setting is to take a final snapshot. You must include either `--final-db-snapshot-identifier` or `--skip-final-snapshot`.
The following AWS CLI code deletes the cluster `sample-cluster` with a final snapshot. The operation fails if there are any instances associated with the cluster or if deletion protection is enabled.
**Example**
For Linux, macOS, or Unix:
```
aws docdb delete-db-cluster \
--db-cluster-identifier sample-cluster \
--final-db-snapshot-identifier sample-cluster-final-snapshot
```
For Windows:
```
aws docdb delete-db-cluster ^
--db-cluster-identifier sample-cluster ^
--final-db-snapshot-identifier sample-cluster-final-snapshot
```
**Example**
The following AWS CLI code deletes the cluster `sample-cluster` without taking a final snapshot.
For Linux, macOS, or Unix:
```
aws docdb delete-db-cluster \
--db-cluster-identifier sample-cluster \
--skip-final-snapshot
```
For Windows:
```
aws docdb delete-db-cluster ^
--db-cluster-identifier sample-cluster ^
--skip-final-snapshot
```
The output of the `delete-db-cluster` operation is the cluster you are deleting.
It takes several minutes for the cluster to be deleted. To monitor the status of the cluster, see [Monitoring a cluster's status](monitoring_docdb-cluster_status.md).
------
# Scaling Amazon DocumentDB clusters
Amazon DocumentDB enables you to scale the storage and compute in your clusters based on your needs. This section describes how you can use storage scaling, instance scaling, and read scaling to manage performance and scaling for your Amazon DocumentDB clusters and instances.
**Topics**
+ [Storage scaling](#db-cluster-manage-scaling-storage)
+ [Instance scaling](#db-cluster-manage-scaling-instance)
+ [Read scaling](#db-cluster-manage-scaling-reads)
+ [Write scaling](#db-cluster-manage-scaling-writes)
## Storage scaling
Amazon DocumentDB storage automatically scales with the data in your cluster volume. As your data grows, your cluster volume storage grows in 10 GiB increments, up to 128 TiB.
## Instance scaling
You can scale your Amazon DocumentDB cluster as needed by modifying the instance class for each instance in the cluster. Amazon DocumentDB supports several instance classes that are optimized for Amazon DocumentDB.
For more information, see [Modifying an Amazon DocumentDB instance](db-instance-modify.md).
## Read scaling
You can achieve read scaling for your Amazon DocumentDB cluster by creating up to 15 Amazon DocumentDB replicas in the cluster. Each Amazon DocumentDB replica returns the same data from the cluster volume with minimal replica lag—usually less than 100 milliseconds after the primary instance has written an update. As your read traffic increases, you can create additional Amazon DocumentDB replicas and connect to them directly to distribute the read load for your cluster. Amazon DocumentDB replicas don't have to be of the same instance class as the primary instance.
For more information, see [Adding an Amazon DocumentDB instance to a cluster](db-instance-add.md).
To read scale with Amazon DocumentDB, we recommend that you connect to your cluster as a replica set and distribute reads to replica instances using the built-in read preference capabilities of your driver. For more information, please see [Connecting to Amazon DocumentDB as a replica set](connect-to-replica-set.md).
## Write scaling
You can scale write capacity on your Amazon DocumentDB cluster by increasing the size of your cluster’s primary instance. This section provides two methods for scaling your cluster’s primary instance based on your needs. The first option seeks to minimize application impact but requires more steps to complete. The second option optimizes for simplicity as it has fewer steps, but it comes with the tradeoff of having more potential impact to your application.
Depending on your application, you can choose what approach below is best for you. For more information about available instance sizes and costs, see the [Amazon DocumentDB Pricing](https://aws.amazon.com/documentdb/pricing/) page.
1. **Optimize for high availability and performance** — If you are connecting to your cluster in [replica set mode](connect-to-replica-set.md) (recommended), you can use the following process to minimize the impact to your application when scaling your primary instance. This method minimizes impact because it keeps your cluster at or above your high availability, and read scaling targets are added to the cluster as instances, instead of being updated in place.
1. Add one or more replicas of the larger instance type to your cluster (see [Adding an Amazon DocumentDB instance to a cluster](db-instance-add.md)). We recommend all replicas be of the same or larger instance type as the primary. This avoids an unintentional reduction in write performance from failing over to a smaller instance type. For most customers, this means temporarily doubling the number of instances in their cluster, then removing the smaller replicas after scaling is complete.
1. Set the failover tier on all new replicas to priority zero, ensuring a replica of the smaller instance type has the highest failover priority. For more information, see [Controlling the failover target](failover.md#failover-target_control).
1. Initiate a manual failover, which will promote one of the new replicas to be the primary instance. For more information, see [Testing failover](failover.md#failover-testing).
**Note**
This will incur \$130 seconds of downtime for your cluster. Please plan accordingly.
1. Remove all replicas of an instance type smaller than your new primary from the cluster.
1. Set the failover tier of all instances back to the same priority (usually, this means setting them back to 1).
As an example, suppose that you have a cluster that currently contains three `r5.large` instances (one primary and two replicas), and you want to scale to an `r5.xlarge` instance type. To do so, you would first add three `r5.xlarge` replica instances to your cluster and then set the failover tier of the new `r5.xlarge` replicas to zero. Next, you would initiate a manual failover (understanding that your application will experience \$130 seconds of downtime). Once the failover is complete, you would remove all three `r5.large` instances from your cluster, leaving the cluster scaled to `r5.xlarge` instances.
To help optimize costs, Amazon DocumentDB instances are billed in one second increments, with a ten minute minimum charge following a billable status change such as creating, modifying, or deleting an instance. For more information, see [Cost optimization](best_practices.md#best_practices-cost_optimization) in the best practices documentation.
1. **Optimize for simplicity** — This approach optimizes for simplicity. It doesn’t expand and contract the cluster, but it might temporarily reduce your read capacity.
It is possible that changing the instance class of a replica will result in that instance not serving requests for a brief period of time, from a few seconds to less than 30 seconds. If you are connecting to your cluster in [replica set mode](connect-to-replica-set.md) (recommended), then this would reduce your read capacity by one replica (e.g., to 66% capacity in a 3-node cluster, or 75% capacity in a 4-node cluster, etc.) during the scaling operation.
1. Scale one of the replica instances in your cluster. For more information, see [Managing instance classes](db-instance-classes.md).
1. Wait until the instance is available (see [Monitoring an Amazon DocumentDB instance's status](monitoring_docdb-instance_status.md)).
**Note**
This will incur \$130 seconds of downtime for your cluster. Please plan accordingly.
1. Continue executing steps 1 and 2 until all replicas instances have been scaled, one by one.
1. Initiate a manual failover. This will promote one of the replicas to be the primary instance. For more information, see [Amazon DocumentDB Failover](failover.md).
**Note**
This will incur up to 30 seconds of downtime for your cluster, but often takes less time than that. Please plan accordingly.
1. Scale the former primary (now a replica) instance.
# Cloning a volume for an Amazon DocumentDB cluster
By using Amazon DocumentDB cloning, you can create a new cluster that uses the same Amazon DocumentDB cluster volume and has the same data as the original. The process is designed to be fast and cost-effective. The new cluster with its associated data volume is known as a *clone*. Creating a clone is faster and more space-efficient than physically copying the data using other techniques, such as restoring a snapshot.
Amazon DocumentDB supports creating an Amazon DocumentDB provisioned clone from a provisioned Amazon DocumentDB cluster. When you create a clone using a different deployment configuration than the source, the clone is created using the latest version of the source's Amazon DocumentDB engine.
When you create clones from your Amazon DocumentDB clusters, the clones are created in your AWS account—the same account that owns the source Amazon DocumentDB cluster.
**Topics**
+ [Overview of Amazon DocumentDB cloning](#db-cloning-overview)
+ [Limitations of Amazon DocumentDB cloning](#db-cloning-limitations)
+ [How Amazon DocumentDB cloning works](#db-how-db-cloning-works)
+ [Creating an Amazon DocumentDB clone](#db-creating-db-clone)
## Overview of Amazon DocumentDB cloning
Amazon DocumentDB uses a *copy-on-write protocol* to create a clone. This mechanism uses minimal additional space to create an initial clone. When the clone is first created, Amazon DocumentDB keeps a single copy of the data that is used by the source DB cluster and the new (cloned) Amazon DocumentDB cluster. Additional storage is allocated only when changes are made to data (on the Amazon DocumentDB storage volume) by the source Amazon DocumentDB cluster or the Amazon DocumentDB cluster clone. To learn more about the copy-on-write protocol, see [How Amazon DocumentDB cloning works](#db-how-db-cloning-works).
Amazon DocumentDB cloning is especially useful for quickly setting up test environments using your production data, without risking data corruption. You can use clones for many types of applications, such as the following:
+ Experiment with potential changes (schema changes and parameter group changes, for example) to assess all impacts.
+ Run workload-intensive operations, such as exporting data or running analytical queries on the clone.
+ Create a copy of your production DB cluster for development, testing, or other purposes.
You can create more than one clone from the same Amazon DocumentDB cluster. You can also create multiple clones from another clone.
After creating an Amazon DocumentDB clone, you can configure the Amazon DocumentDB instances differently from the source Amazon DocumentDB cluster. For example, you might not need a clone for development purposes to meet the same high availability requirements as the source production Amazon DocumentDB cluster. In this case, you can configure the clone with a single Amazon DocumentDB instance rather than the multiple DB instances used by the Amazon DocumentDB cluster.
When you finish using the clone for your testing, development, or other purposes, you can delete it.
## Limitations of Amazon DocumentDB cloning
Amazon DocumentDB; cloning currently has the following limitations:
+ You can create as many clones as you want, up to the maximum number of DB clusters allowed in the AWS Region. However, after you create 15 clones, the next clone is a full copy. The cloning operation acts like a point-in-time recovery.
+ You can't create a clone in a different AWS Region from the source Amazon DocumentDB cluster.
+ You can't create a clone from an Amazon DocumentDB cluster that has no DB instances. You can only clone Amazon DocumentDB clusters that have at least one DB instance.
+ You can create a clone in a different virtual private cloud (VPC) than that of the Amazon DocumentDB cluster. If you do, the subnets of the VPCs must map to the same Availability Zones.
## How Amazon DocumentDB cloning works
Amazon DocumentDB cloning works at the storage layer of an Amazon DocumentDB cluster. It uses a *copy-on-write* protocol that's both fast and space-efficient in terms of the underlying durable media supporting the Amazon DocumentDB storage volume. You can learn more about Amazon DocumentDB cluster volumes in [Managing Amazon DocumentDB clusters](db-clusters.md).
**Topics**
+ [Understanding the copy-on-write protocol](#db-copy-on-write-protocol)
+ [Deleting a source cluster volume](#db-deleting-source-cluster-volume)
### Understanding the copy-on-write protocol
An Amazon DocumentDB cluster stores data in pages in the underlying Amazon DocumentDB storage volume.
For example, in the following diagram you can find an Amazon DocumentDB cluster (A) that has four data pages, 1, 2, 3, and 4. Imagine that a clone, B, is created from the Amazon DocumentDB cluster. When the clone is created, no data is copied. Rather, the clone points to the same set of pages as the source Amazon DocumentDB cluster.
![\[Amazon DocumentDB cluster volume with 4 pages for source cluster, A, and clone, B\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/db-cloning-copy-on-write-protocol-1.png)
When the clone is created, no additional storage is usually needed. The copy-on-write protocol uses the same segment on the physical storage media as the source segment. Additional storage is required only if the capacity of the source segment isn't sufficient for the entire clone segment. If that's the case, the source segment is copied to another physical device.
In the following diagrams, you can find an example of the copy-on-write protocol in action using the same cluster A and its clone, B, as shown preceding. Let's say that you make a change to your Amazon DocumentDB cluster (A) that results in a change to data held on page 1. Instead of writing to the original page 1, Amazon DocumentDB creates a new page 1[A]. The Amazon DocumentDB cluster volume for cluster (A) now points to page 1[A], 2, 3, and 4, while the clone (B) still references the original pages.
![\[Amazon DocumentDB source DB cluster volume and its clone, both with changes.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/db-cloning-copy-on-write-protocol-2.png)
On the clone, a change is made to page 4 on the storage volume. Instead of writing to the original page 4, Amazon DocumentDB creates a new page, 4[B]. The clone now points to pages 1, 2, 3, and to page 4[B], while the cluster (A) continues pointing to 1[A], 2, 3, and 4.
![\[Amazon DocumentDB source DB cluster volume and its clone, both with changes.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/db-cloning-copy-on-write-protocol-3.png)
As more changes occur over time in both the source Amazon DocumentDB cluster volume and the clone, more storage is needed to capture and store the changes.
### Deleting a source cluster volume
When you delete a source cluster volume that has one or more clones associated with it, the clones aren't affected. The clones continue to point to the pages that were previously owned by the source cluster volume.
## Creating an Amazon DocumentDB clone
You can create a clone in the same AWS account as the source Amazon DocumentDB cluster. To do so, you can use the AWS Management Console or the AWS CLI and the procedures following.
By using Amazon DocumentDB cloning, you can create a provisioned Amazon DocumentDB cluster clone from a provisioned Amazon DocumentDB cluster.
------
#### [ Using the AWS Management Console ]
The following procedure describes how to clone an Amazon DocumentDB cluster using the AWS Management Console.
Creating a clone using the AWS Management Console results in an Amazon DocumentDB cluster with one Amazon DocumentDB instance.
These instructions apply for DB clusters owned by the same AWS account that is creating the clone. The DB cluster must be owned by the same AWS account as cross-account cloning is not supported in Amazon DocumentDB.
**To create a clone of a DB cluster owned by your AWS account using the AWS Management Console**
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. Choose your Amazon DocumentDB cluster from the list, and for **Actions**, choose **Create clone**.
![\[Creating a clone starts by selecting your Amazon DocumentDB cluster.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/db-cloning-create-clone-1.png)
The Create clone page opens, where you can configure a **Cluster identifier** and an **Instance class**, and other options for the Amazon DocumentDB cluster clone.
1. In the **Settings** section, do the following:
1. For **Cluster identifier**, enter the name that you want to give to your cloned Amazon DocumentDB cluster.
1. For **Instance configuration**, select an appropriate **Instance class** for your cloned Amazon DocumentDB cluster.
![\[Creating a clone starts by selecting your Amazon DocumentDB cluster and specifying a DB instance size.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/db-cloning-create-clone-2.png)
1. For **Network settings**, choose a **Subnet group** for your use case and the associated VPC security groups.
1. For **Encryption-at-rest**, if the source cluster (the cluster that is being cloned) has encryption enabled, the cloned cluster must also have encryption enabled. If this scenario is true, then the **Enable encryption** options are grayed out (disabled) but with the **Enable encryption** choice selected. Conversely, if the source cluster does not have encryption enabled, the **Enable encryption** options are available and you can choose to enable or disable encryption.
![\[Specify network and encryption settings for your Amazon DocumentDB cluster clone.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/db-cloning-create-clone-3-nw-encryption.png)
1. Complete the new cluster clone configuration by selecting the type of logs to export (optional), entering a specific port used to connect to the cluster, and enabling protection from accidentally deleting the cluster (enabled by default).
![\[Complete the new clone configuration by optionally selecting the type of logs to export, a specific port used to connect to the cluster, and protection form accidentally deleting the cluster.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/db-cloning-create-clone-4-log-options-del-prot-b.png)
1. Finish entering all settings for your Amazon DocumentDB cluster clone. To learn more about Amazon DocumentDB cluster and instance settings, see [Managing Amazon DocumentDB clusters](db-clusters.md).
1. Choose **Create clone** to launch the Amazon DocumentDB clone of your chosen Amazon DocumentDB cluster.
When the clone is created, it's listed with your other Amazon DocumentDB clusters in the console **Databases** section and displays its current state. Your clone is ready to use when its state is **Available**.
------
#### [ Using the AWS CLI ]
Using the AWS CLI for cloning your Amazon DocumentDB cluster involves a couple of steps.
The `restore-db-cluster-to-point-in-time` AWS CLI command that you use results in an empty Amazon DocumentDB cluster with 0 Amazon DocumentDB instances. That is, the command restores only the Amazon DocumentDB cluster, not the DB instances for that cluster. You do that separately after the clone is available. The two steps in the process are as follows:
1. Create the clone by using the [restore-db-cluster-to-point-in-time](https://docs.aws.amazon.com/cli/latest/reference/rds/restore-db-cluster-to-point-in-time.html) CLI command. The parameters that you use with this command control the capacity type and other details of the empty Amazon DocumentDB cluster (clone) being created.
1. Create the Amazon DocumentDB instance for the clone by using the [create-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-instance.html) CLI command to recreate the Amazon DocumentDB instance in the restored Amazon DocumentDB cluster.
The commands following assume that the AWS CLI is set up with your AWS Region as the default. This approach saves you from passing the `--region` name in each of the commands. For more information, see [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html). You can also specify the `--region` in each of the CLI commands that follow.
**Topics**
**Creating the clone**
The specific parameters that you pass to the `[restore-db-cluster-to-point-in-time](https://docs.aws.amazon.com/cli/latest/reference/rds/restore-db-cluster-to-point-in-time.html)` CLI command vary. What you pass depends on the type of clone that you want to create.
Use the following procedure to create a provisioned Amazon DocumentDB clone from a provisioned Amazon DocumentDB cluster.
**To create a clone of the same engine mode as the source Amazon DocumentDB cluster**
+ Use the `[restore-db-cluster-to-point-in-time](https://docs.aws.amazon.com/cli/latest/reference/rds/restore-db-cluster-to-point-in-time.html)` CLI command and specify values for the following parameters:
+ `--db-cluster-identifier` – Choose a meaningful name for your clone. You name the clone when you use the [restore-db-cluster-to-point-in-time](https://docs.aws.amazon.com/cli/latest/reference/rds/restore-db-cluster-to-point-in-time.html) CLI command.
+ `--restore-type` – Use `copy-on-write` to create a clone of the source DB cluster. Without this parameter, the `restore-db-cluster-to-point-in-time` restores the Amazon DocumentDB cluster rather than creating a clone. Default for `restore-type` is `full-copy`.
+ `--source-db-cluster-identifier` – Use the name of the source Amazon DocumentDB cluster that you want to clone.
+ `--use-latest-restorable-time` – This value points to the latest restorable volume data for the clone. This parameter is required for `restore-type copy-on-write`, however, you can not use the `restore-to-time parameter` with it.
The following example creates a clone named `my-clone` from a cluster named `my-source-cluster`.
For Linux, macOS, or Unix:
```
aws docdb restore-db-cluster-to-point-in-time \
--source-db-cluster-identifier my-source-cluster \
--db-cluster-identifier my-clone \
--restore-type copy-on-write \
--use-latest-restorable-time
```
For Windows:
```
aws docdb restore-db-cluster-to-point-in-time ^
--source-db-cluster-identifier my-source-cluster ^
--db-cluster-identifier my-clone ^
--restore-type copy-on-write ^
--use-latest-restorable-time
```
The command returns the JSON object containing details of the clone. Check to make sure that your cloned DB cluster is available before trying to create the DB instance for your clone. For more information, see Checking the status and getting clone details below:
**Checking the status and getting clone details**
You can use the following command to check the status of your newly created empty DB cluster.
```
$ aws docdb describe-db-clusters --db-cluster-identifier my-clone --query '*[].[Status]' --output text
```
Or you can obtain the status and the other values that you need to create the DB instance for your clone by using the following AWS CLI query:
For Linux, macOS, or Unix:
```
aws docdb describe-db-clusters --db-cluster-identifier my-clone \
--query '*[].{Status:Status,Engine:Engine,EngineVersion:EngineVersion}'
```
For Windows:
```
aws docdb describe-db-clusters --db-cluster-identifier my-clone ^
--query "*[].{Status:Status,Engine:Engine,EngineVersion:EngineVersion}"
```
This query returns output similar to the following.
```
[
{
"Status": "available",
"Engine": "docdb",
"EngineVersion": "4.0.0",
}
]
```
**Creating the Amazon DocumentDB instance for your clone**
Use the [create-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-instance.html) CLI command to create the DB instance for your clone.
The `--db-instance-class` parameter is used for provisioned Amazon DocumentDB clusters only.
For Linux, macOS, or Unix:
```
aws docdb create-db-instance \
--db-instance-identifier my-new-db \
--db-cluster-identifier my-clone \
--db-instance-class db.r5.4xlarge \
--engine docdb
```
For Windows:
```
aws docdb create-db-instance ^
--db-instance-identifier my-new-db ^
--db-cluster-identifier my-clone ^
--db-instance-class db.r5.4xlarge ^
--engine docdb
```
**Parameters to use for cloning**
The following table summarizes the various parameters used with `restore-db-cluster-to-point-in-time` to clone Amazon DocumentDB clusters.
| Parameter | Description |
| --- | --- |
| --source-db-cluster-identifier | Use the name of the source Amazon DocumentDB cluster that you want to clone. |
| --db-cluster-identifier | Choose a meaningful name for your clone. You name your clone with the ` restore-db-cluster-to-point-in-time` command. Then you pass this name to the `create-db-instance` command. |
| --restore-type | Specify `copy-on-write` as the `--restore-type` to create a clone of the source DB cluster rather than restoring the source Amazon DocumentDB cluster. |
| --use-latest-restorable-time | This value points to the latest restorable volume data for the clone. |
------
# Understanding Amazon DocumentDB cluster fault tolerance
Amazon DocumentDB clusters are fault tolerant by design. Each cluster's volume spans multiple Availability Zones in a single AWS Region, and each Availability Zone contains a copy of the cluster's volume data. This functionality means that your cluster can tolerate an Availability Zone failure without any loss of data and only a brief interruption of service.
If the primary instance in a cluster fails, Amazon DocumentDB automatically performs a failover to a new primary instance in one of two ways:
+ By promoting an existing Amazon DocumentDB replica to the new primary instance chosen based on the Promotion Tier setting of each replica, and then creating a replacement for the former primary. A failover to the replica instance typically takes less than 30 seconds. Read and write operations may experience brief interruption during this period. To increase the availability of your cluster, we recommend that you create at least one or more Amazon DocumentDB replicas in two or more different Availability Zones.
+ By creating a new primary instance. This only happens if you do not have a replica instance in your cluster and can take a few minutes to complete.
If the cluster has one or more Amazon DocumentDB replicas, an Amazon DocumentDB replica is promoted to the primary instance during a failure event. A failure event results in a brief interruption, during which read and write operations fail with an exception. However, service is typically restored in less than 120 seconds, and often less than 60 seconds. To increase the availability of your cluster, we recommend that you create at least one or more Amazon DocumentDB replicas in two or more different Availability Zones.
You can customize the order in which your Amazon DocumentDB replicas are promoted to the primary instance after a failure by assigning each replica a priority. Priorities range from 0 for the highest priority to 15 for the lowest priority. If the primary instance fails, the Amazon DocumentDB replica with the highest priority is promoted to the new primary instance. You can modify the priority of an Amazon DocumentDB replica at any time. Modifying the priority doesn't trigger a failover. You can use the `modify-db-instance` operation with the `--promotion-tier` parameter. For more information about customizing the failover priority of an instance, see [Amazon DocumentDB Failover](failover.md).
More than one Amazon DocumentDB replica can share the same priority, resulting in promotion tiers. If two or more Amazon DocumentDB replicas share the same priority, then the replica that is largest in size is promoted to primary. If two or more Amazon DocumentDB replicas share the same priority and size, an arbitrary replica in the same promotion tier is promoted.
If the cluster doesn't contain any Amazon DocumentDB replicas, the primary instance is re-created during a failure event. A failure event results in an interruption, during which read and write operations fail with an exception. Service is restored when the new primary instance is created, which typically takes less than 10 minutes. Promoting an Amazon DocumentDB replica to the primary instance is much faster than creating a new primary instance.