# 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 or 5.0 to 8.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).
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).
------