# Managing Amazon DocumentDB elastic clusters To manage an Amazon DocumentDB elastic 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. The Amazon DocumentDBFullAccess policy provides all the required permissions for administering an Amazon DocumentDB elastic cluster. The following topics show how to perform various tasks when working with Amazon DocumentDB elastic clusters. **Topics** + [ ## Modifying elastic cluster configurations ](#elastic-modify) + [ ## Monitoring an elastic cluster ](#elastic-monitor) + [ ## Deleting an elastic cluster ](#elastic-delete) + [ # Managing elastic cluster snapshots ](elastic-manage-snapshots.md) + [ # Stopping and starting an Amazon DocumentDB elastic cluster ](elastic-cluster-stop-start.md) + [ # Maintaining Amazon DocumentDB elastic clusters ](elastic-cluster-maintenance.md) ## Modifying elastic cluster configurations In this section we explain how to modify elastic cluster, using either the AWS Management Console or AWS CLI with the following instructions. A primary use of modifying the cluster is to scale shards by increasing or decreasing the shard count and/or shard compute capacity. ------ #### [ Using the AWS Management Console ] To modify an elastic cluster configuration using the AWS Management Console: 1. Sign into the [AWS Management Console](https://console.aws.amazon.com/docdb/home?region=us-east-1) and open the Amazon DocumentDB console. 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 in the upper-left corner of the navigation pane. 1. Choose the name of the cluster you want to modify in the **Cluster identifier** column. 1. Choose **Modify**. 1. Edit the fields you want changed and then select **Modify cluster**. ![\[Form showing configuration, maintenance, authentication, and network settings options that can be modified, with Modify cluster button in the bottom-right corner.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/cluster-shard-modify-3.png) **Note** Alternatively, you can access the **Modify cluster** dialog by going to the **Clusters** page, checking the box next to your cluster, choosing **Actions**, then **Modify**. ------ #### [ Using the AWS CLI ] To modify an elastic cluster configuration using the AWS CLI, use the `update-cluster` operation with the following parameters: + **--cluster-arn**—Required. The ARN identifier of the cluster that you want to modify. + **--shard-capacity**—Optional. The number of vCPUs assigned to each shard. Maximum is 64. Allowed values are 2, 4, 8, 16, 32, 64. + **--shard-count**—Optional. The number of shards assigned to the cluster. Maximum is 32. + **--shard-instance**-count—Optional. The number of replica instances applying to all shards in this cluster. Maximum is 16. + **--auth-type**—Optional. The authentication type used to determine where to fetch the password used for accessing the elastic cluster. Valid types are `PLAIN_TEXT` or `SECRET_ARN`. + **--admin-user-password**—Optional. The password associated with the admin user. + **--vpc-security-group-ids**—Optional. Configure a list of Amazon EC2 and Amazon Virtual Private Cloud (VPC) security groups to associate with this cluster. + **--preferred-maintenance-window**—Optional. Configure the weekly time range during which system maintenance can occur, in Universal Coordinated Time (UTC) The format is: `ddd:hh24:mi-ddd:hh24:mi`. Valid days (ddd): Mon, Tue, Wed, Thu, Fri, Sat, Sun The default is a 30-minute window selected at random from an 8-hour block of time for each Amazon Web Services Region, occurring on a random day of the week. Minimum 30-minute window. + **--subnet-ids**—Optional. Configure network subnet Ids. In the following example, replace each *user input placeholder* with your own information. For Linux, macOS, or Unix: ``` aws docdb-elastic update-cluster \ --cluster-arn arn:aws:docdb-elastic:us-east-1:477568257630:cluster/b9f1d489-6c3e-4764-bb42-da62ceb7bda2 \ --shard-capacity 8 \ --shard-count 4 \ --shard-instance-count 3 \ --admin-user-password testPassword \ --vpc-security-group-ids ec-65f40350 \ --subnet-ids subnet-9253c6a3, subnet-9f1b5af9 ``` For Windows: ``` aws docdb-elastic update-cluster ^ --cluster-arn arn:aws:docdb-elastic:us-east-1:477568257630:cluster/b9f1d489-6c3e-4764-bb42-da62ceb7bda2 ^ --shard-capacity 8 ^ --shard-count 4 ^ --shard-instance-count 3 ^ --admin-user-password testPassword ^ --vpc-security-group-ids ec-65f40350 ^ --subnet-ids subnet-9253c6a3, subnet-9f1b5af9 ``` ------ To monitor the status of the elastic cluster after your modification, see Monitoring an elastic cluster. ## Monitoring an elastic cluster In this section, we explain how to monitor your elastic cluster, using either the AWS Management Console or AWS CLI with the following instructions. ------ #### [ Using the AWS Management Console ] To monitor an elastic cluster configuration using the AWS Management Console: 1. Sign into the [AWS Management Console](https://console.aws.amazon.com/docdb/home?region=us-east-1) and open the Amazon DocumentDB console. 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 in the upper-left corner of the navigation pane. 1. Choose the name of the cluster you want to monitor in the **Cluster identifier** column. 1. Choose the **Monitoring** tab. ![\[Elastic cluster summary information shown in the Monitoring tab.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/cluster-shard-monitor-2.png) A number of charts from Amazon CloudWatch are displayed for the following monitoring categories: + Resource Utilization + Throughput + Operations + System You can also access Amazon CloudWatch through the AWS Management Console to set up your own monitoring environment for your elastic clusters. ------ #### [ Using the AWS CLI ] To monitor a specific elastic cluster configuration using the AWS CLI, use the `get-cluster` operation with the following parameters: + **--cluster-arn**—Required. The ARN identifier of the cluster for which you want information. In the following example, replace each *user input placeholder* with your own information. For Linux, macOS, or Unix: ``` aws docdb-elastic get-cluster \ --cluster-arn arn:aws:docdb-elastic:us-west-2:123456789012:cluster:/68ffcdf8-e3af-40a3-91e4-24736f2dacc9 ``` For Windows: ``` aws docdb-elastic get-cluster ^ --cluster-arn arn:aws:docdb:-elastic:us-west-2:123456789012:cluster:/68ffcdf8-e3af-40a3-91e4-24736f2dacc9 ``` The output from this operation looks something like the following: ``` "cluster": { ... "clusterArn": "arn:aws:docdb-elastic:us-west-2:123456789012:cluster:/68ffcdf8-e3af-40a3-91e4-24736f2dacc9", "clusterEndpoint": "stretch-11-477568257630.us-east-1.docdb-elastic.amazonaws.com", "readerEndpoint": "stretch-11-477568257630-ro.us-east-1.docdb-elastic.amazonaws.com", "clusterName": "stretch-11", "shardCapacity": 2, "shardCount": 3, "shardInstanceCount: 5, "status": "ACTIVE", ... } ``` For more information, see `DescribeClusterSnapshot` in the Amazon DocumentDB Resource Management API Reference. To view the details of all elastic clusters using the AWS CLI, use the `list-clusters` operation with the following parameters: + **--next-token**—Optional. If the number of items output (`--max-results`) is fewer than the total number of items returned by the underlying API calls, the output includes a `NextToken` that you can pass to a subsequent command to retrieve the next set of items. + **--max-results**—Optional. The total number of items to return in the command's output. If more results exist than the specified `max-results` value, a pagination token (`next-token`) is included in the response so that the remaining results can be retrieved. + Default: 100 + Minimum 20, maximum 100 In the following example, replace each *user input placeholder* with your own information. For Linux, macOS, or Unix: ``` aws docdb-elastic list-clusters \ --next-token eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ== \ --max-results 2 ``` For Windows: ``` aws docdb-elastic list-clusters ^ --next-token eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ== ^ --max-results 2 ``` The output from this operation looks something like the following: ``` { "Clusters": [ { "ClusterIdentifier":"mycluster-1", "ClusterArn":"arn:aws:docdb:us-west-2:123456789012:sharded-cluster:sample-cluster" "Status":"available", "ClusterEndpoint":"sample-cluster.sharded-cluster-corcjozrlsfc.us-west-2.docdb.amazonaws.com" } { "ClusterIdentifier":"mycluster-2", "ClusterArn":"arn:aws:docdb:us-west-2:987654321098:sharded-cluster:sample-cluster" "Status":"available", "ClusterEndpoint":"sample-cluster2.sharded-cluster-corcjozrlsfc.us-west-2.docdb.amazonaws.com" } ] } ``` ------ ## Deleting an elastic cluster In this section we explain how to delete an elastic cluster, using either the AWS Management Console or AWS CLI with the following instructions. ------ #### [ Using the AWS Management Console ] To delete an elastic cluster configuration using the AWS Management Console: 1. Sign into the [AWS Management Console](https://console.aws.amazon.com/docdb/home?region=us-east-1) and open the Amazon DocumentDB console. 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 in the upper-left corner of the navigation pane. 1. In the cluster list table, select the check box to the left of the cluster name you want to delete and then choose **Actions**. From the dropdown menu, choose **Delete**. 1. In the **Delete "cluster-name" elastic cluster?** dialog box, choose **Delete**. ![\[Delete dialog box, with Delete button in the lower-right corner.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/cluster-delete-dialog.png) 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](https://docs.aws.amazon.com//documentdb/latest/developerguide/monitoring_docdb-cluster_status.html). ------ #### [ Using the AWS CLI ] To delete an elastic cluster using the AWS CLI, use the `delete-cluster` operation with the following parameters:: + **--cluster-arn**—Required. The ARN identifier of the cluster that you want to delete. + **--no-skip-final-backup**—Optional. If you want a final backup, you must include this parameter with a name for the final backup. You must include either `--final-backup-identifier` or `--skip-final-backup`. + **--skip-final-backup**—Optional. Use this parameter only if you don't want to take a final backup before deleting your cluster. The default setting is to take a final snapshot. The following AWS CLI code examples delete a cluster with an ARN of arn:aws:docdb:us-west-2:123456789012:sharded-cluster:sample-cluster with a final backup. In the following example, replace each *user input placeholder* with your own information.. For Linux, macOS, or Unix: ``` aws docdb-elastic delete-cluster \ --cluster-arn arn:aws:docdb:us-west-2:123456789012:sharded-cluster:sample-cluster \ --no-skip-final-backup \ --final-backup-identifier finalArnBU-arn:aws:docdb:us-west-2:123456789012:sharded-cluster:sample-cluster ``` For Windows: ``` aws docdb-elastic delete-cluster ^ --cluster-arn arn:aws:docdb:us-west-2:123456789012:sharded-cluster:sample-cluster ^ --no-skip-final-backup ^ --final-backup-identifier finalArnBU-arn:aws:docdb:us-west-2:123456789012:sharded-cluster:sample-cluster ``` The following AWS CLI code examples delete a cluster with an ARN of arn:aws:docdb:us-west-2:123456789012:sharded-cluster:sample-cluster without taking a final backup. In the following example, replace each *user input placeholder* with your own information. For Linux, macOS, or Unix: ``` aws docdb-elastic delete-cluster \ --cluster-arn arn:aws:docdb:us-west-2:123456789012:sharded-cluster:sample-cluster \ --skip-final-backup \ ``` For Windows: ``` aws docdb-elastic delete-cluster ^ --cluster-arn arn:aws:docdb:us-west-2:123456789012:sharded-cluster:sample-cluster ^ --skip-final-backup ^ ``` The output of the `delete-cluster` operation is a display of the cluster you are deleting. 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](https://docs.aws.amazon.com/documentdb/latest/developerguide/monitoring_docdb-cluster_status.html). ------ # Managing elastic cluster snapshots Manual snapshots can be taken after an elastic cluster has been created. Automated backups are created the moment the elastic cluster snapshot is created. **Note** Your elastic cluster must be in the `Available` state for a manual snapshot to be taken. This section explains how you can create, view, restore from, and delete elastic cluster snapshots. The following topics show how to perform various tasks when working with Amazon DocumentDB elastic cluster snapshots. **Topics** + [ ## Creating a manual elastic cluster snapshot ](#elastic-create-snapshot) + [ ## Viewing an elastic cluster snapshot ](#elastic-view-snapshot) + [ ## Restoring an elastic cluster from a snapshot ](#elastic-restore-snapshot) + [ ## Copying an elastic cluster snapshot ](#elastic-copy-snapshot) + [ ## Deleting an elastic cluster snapshot ](#elastic-delete-snapshot) + [ ## Managing an elastic cluster snapshot automatic backup ](#elastic-auto-snapshot) ## Creating a manual elastic cluster snapshot In this section we explain how to create a manual elastic cluster snapshot, using either the AWS Management Console or AWS CLI with the following instructions. ------ #### [ Using the AWS Management Console ] To create a manual elastic cluster snapshot using the AWS Management Console: 1. Sign into the [AWS Management Console](https://console.aws.amazon.com/docdb/home?region=us-east-1) and open the Amazon DocumentDB console. 1. In the navigation pane, choose **Snapshots**. **Tip** If you don't see the navigation pane on the left side of your screen, choose the menu icon in the upper-left corner of the navigation pane. 1. On the **Snapshots** page, choose **Create**. 1. On the **Create cluster snapshot** page, in the **Cluster identifier** field, choose your elastic cluster from the drop down list. In the **Snapshot identifier** field, enter a unique identifier for your elastic cluster. Choose **Create**. ![\[Diagram: elastic cluster create snapshot\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/elastic-create-snapshot.png) **Note** Alternatively, you can access the **Create cluster snapshot** dialog by going to the **Clusters** page, checking the box next to your cluster, then choosing **Actions**, then **Take snapshot**. Your elastic cluster snapshot is now provisioning. This can take up to a few minutes to finish. You can view and restore from your snapshot when the status shows as `Available` in the **Snapshots** list. ------ #### [ Using the AWS CLI ] To create a manual elastic cluster snapshot using the AWS CLI, use the `create-cluster-snapshot` operation with the following parameters: + **--snapshot-name**—Required. The name of the cluster snapshot you want to create. + **--cluster-arn**—Required. The ARN identifier of the cluster of which you want to create a snapshot. In the following example, replace each *user input placeholder* with your own information. For Linux, macOS, or Unix: ``` aws docdb-elastic create-cluster-snapshot \ --snapshot-name sample-snapshot-1 \ --cluster-arn arn:aws:docdb:us-west-2:123456789012:sharded-cluster:sample-cluster ``` For Windows: ``` aws docdb-elastic create-cluster-snapshot ^ --snapshot-name sample-snapshot-1 ^ --cluster-arn arn:aws:docdb:us-west-2:123456789012:sharded-cluster:sample-cluster ``` ------ ## Viewing an elastic cluster snapshot In this section we explain how to view elastic cluster snapshot information, using either the AWS Management Console or AWS CLI with the following instructions. ------ #### [ Using the AWS Management Console ] To view information about a specific elastic cluster snapshot using the AWS Management Console: 1. Sign into the [AWS Management Console](https://console.aws.amazon.com/docdb/home?region=us-east-1) and open the Amazon DocumentDB console. 1. In the navigation pane, choose **Snapshots**. **Tip** If you don't see the navigation pane on the left side of your screen, choose the menu icon in the upper-left corner of the navigation pane. 1. On the **Snapshots** page, choose your snapshot from the list by clicking on the name in **Snapshot identifier** column. 1. View your snapshot's information in **Details**. ![\[Diagram: elastic cluster view snapshot\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/elastic-snapshot-view.png) ------ #### [ Using the AWS CLI ] To view information about a specific elastic cluster snapshot using the AWS CLI, use the `get-cluster-snapshot` operation with the following parameters: + **--snapshot-arn**—Required. The ARN identifier of the snapshot for which you want information. In the following example, replace each *user input placeholder* with your own information. For Linux, macOS, or Unix: ``` aws docdb-elastic get-cluster-snapshot \ --snapshot-arn sampleResourceName ``` For Windows: ``` aws docdb-elastic get-cluster-snapshot ^ --snapshot-arn sampleResourceName ``` To view information about a specific elastic cluster snapshot using the AWS CLI, use the `get-cluster-snapshot` operation with the following parameters: + **--snapshot-arn**—Required. The ARN identifier of the snapshot for which you want information. In the following example, replace each *user input placeholder* with your own information. For Linux, macOS, or Unix: ``` aws docdb-elastic get-cluster-snapshot \ --snapshot-arn sampleResourceName ``` For Windows: ``` aws docdb-elastic get-cluster-snapshot ^ --snapshot-arn sampleResourceName ``` To view information about all elastic cluster snapshots using the AWS CLI, use the `list-cluster-snapshots` operation with the following parameters: + **--snapshot-type**—Optional. The type of cluster snapshots to be returned. You can specify one of the following values: + `automated` - Return all cluster snapshots that Amazon DocumentDB has automatically created for your AWS account. + `manual` - Return all cluster snapshots that you have manually created for your AWS account. + `shared` - Return all manual cluster snapshots that have been shared to your AWS account. + `public` - Return all cluster snapshots that have been marked as public. + **--next-token**—Optional. An optional pagination token provided by a previous request. If this parameter is specified, the response includes only records beyond the this token, up to the value specified by `max-results`. + **--max-results**—Optional. The maximum number of results to include in the response. If more results exist than the specified `max-results` value, a pagination token (`next-token`) is included in the response so that the remaining results can be retrieved. + Default: 100 + Minimum 20, maximum 100 In the following example, replace each *user input placeholder* with your own information. For Linux, macOS, or Unix: ``` aws docdb-elastic list-cluster-snapshots \ --snapshot-type value \ --next-token value \ --max-results 50 ``` For Windows: ``` aws docdb-elastic list-cluster-snapshots ^ --snapshot-type value ^ --next-token value ^ --max-results 50 ``` ------ ## Restoring an elastic cluster from a snapshot In this section we explain how to restore an elastic cluster from a snapshot, using either the AWS Management Console or AWS CLI with the following instructions. ------ #### [ Using the AWS Management Console ] To restore an elastic cluster from a snapshot using the AWS Management Console: 1. Sign into the [AWS Management Console](https://console.aws.amazon.com/docdb/home?region=us-east-1) and open the Amazon DocumentDB console. 1. In the navigation pane, choose **Snapshots**. **Tip** If you don't see the navigation pane on the left side of your screen, choose the menu icon in the upper-left corner of the navigation pane. 1. Choose the button to the left of the snapshot, that you want to use to restore a cluster, in the **Snapshot identifier** column. 1. Choose **Actions**, then **Restore**. ![\[Diagram: elastic cluster restore from snapshot\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/elastic-restore-snapshot.png) 1. On the **Restore snapshot** page, enter a name for the new cluster in the **Cluster identifier** field. **Note** For any manual snapshot restoration, you must create a new cluster. 1. In the **Virtual Private Cloud (VPC)** field, choose a VPC from the drop-down list. 1. For **Subnets** and **VPC security groups**, you can use the defaults or select three subnets of your choice and upto three VPC security groups (minimum one). 1. If you are satisfied with the cluster configuration, choose **Restore cluster** and wait while your cluster is restored. ------ #### [ Using the AWS CLI ] To restore an elastic cluster from a snapshot using the AWS CLI, use the `restore-cluster-from-snapshot` operation with the following parameters: + **--cluster-name**—Required. The current name of the elastic cluster as entered during creation or last modified. + **--snapshot-arn**—Required. The ARN identifier of the snapshot being used to restore the cluster. + **--vpc-security-group-ids**—Optional. One or more Amazon EC2 and Amazon Virtual Private Cloud (VPC) security groups to associate with the cluster. + **--kms-key-id**—Optional. Configure the KMS key identifier for an encrypted cluster. The KMS key identifier is the Amazon Resource Name (ARN) for the AWS KMS encryption key. If you are creating a cluster using the same Amazon Web Services account that owns the KMS encryption key that is used to encrypt the new cluster, you can use the KMS key alias instead of the ARN for the KMS encryption key. If an encryption key is not specified in KmsKeyId and if the `StorageEncrypted` parameter is true, Amazon DocumentDB uses your default encryption key. + **--subnet-ids**—Optional. Network subnet Ids. In the following example, replace each *user input placeholder* with your own information.. For Linux, macOS, or Unix: ``` aws docdb-elastic restore-cluster-from-snapshot \ --cluster-name elastic-sample-cluster \ --snapshot-arn sampleResourceName \ --vpc-security-group-ids value ec-65f40350 \ --kms-key-id arn:aws:docdb-elastic:us-east-1:477568257630:cluster/b9f1d489-6c3e-4764-bb42-da62ceb7bda2 \ --subnet-ids subnet-9253c6a3, subnet-9f1b5af9 ``` For Windows: ``` aws docdb-elastic restore-cluster-from-snapshot ^ --cluster-name elastic-sample-cluster ^ --snapshot-arn sampleResourceName ^ --vpc-security-group-ids value ec-65f40350 ^ --kms-key-id arn:aws:docdb-elastic:us-east-1:477568257630:cluster/b9f1d489-6c3e-4764-bb42-da62ceb7bda2 ^ --subnet-ids subnet-9253c6a3, subnet-9f1b5af9 ``` ------ ## Copying an elastic cluster snapshot In Amazon DocumentDB, you can copy manual and automatic elastic cluster snapshots within the same region and within the same account. In this section we explain how to copy an elastic cluster snapshot, using either the AWS Management Console or AWS CLI. ------ #### [ Using the AWS Management Console ] To copy an elastic cluster snapshot using the AWS Management Console: 1. Sign into the [AWS Management Console](https://console.aws.amazon.com/docdb/home?region=us-east-1) and open the Amazon DocumentDB console. 1. In the navigation pane, choose **Snapshots**. **Tip** If you don't see the navigation pane on the left side of your screen, choose the menu icon in the upper-left corner of the navigation pane. 1. Choose the button to the left of the snapshot, that you want to copy, in the **Snapshot identifier** column. 1. Choose **Actions**, then **Copy**. ![\[Diagram: elastic cluster copy snapshot\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/ec-copy-snapshot.png) 1. For **New snapshot identifier**, enter the new snapshot's name. 1. For **Copy Tags**, check the box if you want to copy all tags from the source elastic cluster snapshot to the target elastic cluster snapshot. 1. For **Encryption**, choose either a default AWS KMS key or a KMS key of your choosing. The second option allows you to select an existing KMS key that you already created or allows you to create a new one. 1. Choose **Copy snapshot** when complete. ------ #### [ Using the AWS CLI ] To copy an elastic cluster snapshot using the AWS CLI, use the `copy-cluster-snapshot` operation with the following parameters: + **‐‐source-db-cluster-snapshot-identifier**—Required. The identifier of the existing elastic cluster snapshot being copied. The elastic cluster snapshot must exist and be in the available state. This parameter is not case sensitive. + **‐‐target-db-cluster-snapshot-identifier**—Required. The identifier of the new elastic cluster snapshot to create from the existing cluster snapshot. This parameter is not case sensitive. Target snapshot name constraints: + Cannot be the name of an existing snapshot. + Length is [1—63] letters, numbers, or hyphens. + First character must be a letter. + Cannot end with a hyphen or contain two consecutive hyphens. In the following example, replace each *user input placeholder* with your own information. For Linux, macOS, or Unix: ``` aws docdb-elastic copy-cluster-snapshot \ ‐‐source-cluster-snapshot-arn \ ‐‐target-cluster-snapshot-name my-target-copied-snapshot ``` For Windows: ``` aws docdb-elastic copy-cluster-snapshot ^ ‐‐source-cluster-snapshot-arn ^ ‐‐target-cluster-snapshot-name my-target-copied-snapshot ``` ------ ## Deleting an elastic cluster snapshot In this section we explain how to delete an elastic cluster snapshot, using either the AWS Management Console or AWS CLI. ------ #### [ Using the AWS Management Console ] To restore an elastic cluster from a snapshot using the AWS Management Console: 1. Sign into the [AWS Management Console](https://console.aws.amazon.com/docdb/home?region=us-east-1) and open the Amazon DocumentDB console. 1. In the navigation pane, choose **Snapshots**. **Tip** If you don't see the navigation pane on the left side of your screen, choose the menu icon in the upper-left corner of the navigation pane. 1. Choose the button to the left of the snapshot, that you want to use to restore a cluster, in the **Snapshot identifier** column. 1. Choose **Actions**, then **Delete**. ![\[Diagram: elastic cluster delete snapshot\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/elastic-delete-snapshot.png) 1. On the **Delete "snapshot-name" snapshot** dialog, choose **Delete**. ------ #### [ Using the AWS CLI ] To delete an elastic cluster snapshot using the AWS CLI, use the `delete-cluster-snapshot` operation with the following parameters: + **--snapshot-arn**—Required. The ARN identifier of the snapshot being used to restore the cluster. In the following example, replace each *user input placeholder* with your own information.. For Linux, macOS, or Unix: ``` aws docdb-elastic delete-cluster-snapshot \ --snapshot-arn sampleResourceName ``` For Windows: ``` aws docdb-elastic delete-cluster-snapshot ^ --snapshot-arn sampleResourceName ``` ------ ## Managing an elastic cluster snapshot automatic backup Amazon DocumentDB takes daily snapshots of your elastic clusters. You can specify the preferred backup window and the backup retention period in a new or existing elastic cluster snapshot configuration. In this section we explain how to set automatic backup parameters in an elastic cluster snapshot, using either the AWS Management Console or AWS CLI. ------ #### [ Using the AWS Management Console ] To set an automatic backup for a new elastic cluster snapshot using the AWS Management Console: 1. Sign into the [AWS Management Console](https://console.aws.amazon.com/docdb/home?region=us-east-1) and open the Amazon DocumentDB console. 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 in the upper-left corner of the navigation pane. 1. Choose the button to the left of the cluster, that you want to change the backup settings for, in the **Cluster identifier** column. 1. Choose **Actions**, then **Modify**. 1. In the **Backup** section, edit the fields according to your backup requirements. ![\[Screenshot of the Backup pane showing the steps to configure the cluster backup window.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/ec-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. Choose **Select window** if you want to configure the time and duration when backups are created. **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. **Duration**—In the list, choose the number of hours to be allocated to creating automatic backups. 1. Choose **No preference** if you want Amazon DocumentDB to choose the time and duration when backups are created. 1. Choose **Modify cluster** when complete. ------ #### [ Using the AWS CLI ] To set an automatic backup for a new elastic cluster snapshot using the AWS CLI, use the `create-cluster-snapshot` operation with the following parameters: + **--preferred-backup-window**—Optional. The daily preferred time range during which automated backups are created. The default is a 30-minute window selected at random from an 8-hour block of time for each AWS Region. Constraints: + Must be in the format `hh24:mi-hh24:mi`. + Must be in Universal Coordinated Time (UTC). + Must not conflict with the preferred maintenance window. + Must be at least 30 minutes. + **--backup-retention-period**—Optional. The number of days for which automated backups are retained. The default value is 1. Constraints: + Must specify a minimum value of 1. + Range is from 1 to 35. **Note** Automated backups are only be taken when the cluster is in an ‘active’ state. **Note** You can also modify the `preferred-backup-window` and `backup-retention-period` parameters of an existing elastic cluster using the `aws docdb-elastic update-cluster` command. In the following example, replace each *user input placeholder* with your own information. The following `create-cluster` example creates the Amazon DocumentDB elastic cluster *sample-cluster* with the retention period for automatic backups of *7* days, and a preferred backup window of *18:00-18:30 UTC*. For Linux, macOS, or Unix: ``` aws docdb-elastic create-cluster \ --cluster-name sample-cluster \ --shard-capacity 2 \ --shard-count 2 \ --admin-user-name SampleAdmin \ --auth-type PLAIN_TEXT \ --admin-user-password SamplePass123! \ --preferred-backup-window 18:00-18:30 \ --backup-retention-period 7 ``` For Windows: ``` aws docdb-elastic create-cluster ^ --cluster-name sample-cluster ^ --shard-capacity 2 ^ --shard-count 2 ^ --admin-user-name SampleAdmin ^ --auth-type PLAIN_TEXT ^ --admin-user-password SamplePass123! ^ --preferred-backup-window 18:00-18:30 ^ --backup-retention-period 7 ``` ------ # Stopping and starting an Amazon DocumentDB elastic cluster Stopping and starting Amazon DocumentDB elastic clusters can help you manage costs for development and test environments. Instead of creating and deleting elastic clusters each time you use Amazon DocumentDB, you can temporarily stop your cluster when it isn't needed. You can then start it again when you resume your testing. **Topics** + [ ## Overview of stopping and starting an elastic cluster ](#elastic-cluster-stop-start-overview) + [ ## Operations you can perform on a stopped elastic cluster ](#elastic-cluster-stopped-operations) ## Overview of stopping and starting an elastic cluster During periods where you don't need an Amazon DocumentDB elastic cluster, you can stop the cluster. You can then start the cluster again anytime you need to use it. Starting and stopping simplifies the setup and teardown processes for elastic clusters that are used for development, testing, or similar activities that don't require continuous availability. You can stop and start an elastic cluster using the AWS Management Console or the AWS CLI with a single action. While your elastic 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. Amazon DocumentDB automatically starts your elastic 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 use of the elastic cluster again. While your cluster is stopped, you can't query your storage volume because querying requires that the cluster is in the available state. When an Amazon DocumentDB elastic cluster is stopped, the cluster cannot be modified in any way. This includes deleting the cluster. ------ #### [ Using the AWS Management Console ] The following procedure shows you how to stop an elastic cluster in the available state, or start a stopped elastic cluster. **To stop or start an Amazon DocumentDB elastic 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. ![\[A cluster from the Clusters list, with the checkbox selected to the left of the cluster name.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/cluster-list-ec.png) 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**. ![\[The Actions dropdown list with the Stop option selected.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/ec-stop.png) 1. On the confirmation dialog, confirm that you want to stop the elastic cluster by choosing **Stop cluster**, or to keep the cluster running, choose **Cancel**. ![\[Confirmation dialog for stopping a cluster, with Cancel and Stop cluster buttons on the bottom.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/ec-stop-confirm.png) + If you want to start the cluster, and the cluster is stopped, choose **Start**. ![\[The Actions dropdown list with the Start option selected.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/ec-start.png) 1. Monitor the status of the elastic cluster. If you started the cluster, you can resume using the cluster when the cluster is *available*. For more information, see [Determining a cluster's status](db-cluster-status.md). ![\[Status column in Clusters table showing available and starting statuses.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/ec-starting-status.png) ------ #### [ Using the AWS CLI ] The following code examples show you how to stop an elastic cluster in the active or available state, or start a stopped elastic cluster. To stop an elastic cluster using the AWS CLI, use the `stop-cluster` operation. To start a stopped cluster, use the `start-cluster` operation. Both operations use the `--cluster-arn` parameter. **Parameter:** + **--cluster-arn**—Required. The ARN identifier of the elastic cluster that you want to stop or start. **Example — To stop an elastic cluster using the AWS CLI** In the following example, replace each *user input placeholder* with your own information. The following code stops the elastic cluster with an ARN of `arn:aws:docdb-elastic:us-east-1:477568257630:cluster/b9f1d489-6c3e-4764-bb42-da62ceb7bda2`. The elastic cluster must be in the active or available state. For Linux, macOS, or Unix: ``` aws docdb-elastic stop-cluster \ --cluster-arn arn:aws:docdb-elastic:us-east-1:477568257630:cluster/b9f1d489-6c3e-4764-bb42-da62ceb7bda2 ``` For Windows: ``` aws docdb-elastic stop-cluster ^ --cluster-arn arn:aws:docdb-elastic:us-east-1:477568257630:cluster/b9f1d489-6c3e-4764-bb42-da62ceb7bda2 ``` **Example — To start an elastic cluster using the AWS CLI** In the following example, replace each *user input placeholder* with your own information. The following code starts the elastic cluster with an ARN of `arn:aws:docdb-elastic:us-east-1:477568257630:cluster/b9f1d489-6c3e-4764-bb42-da62ceb7bda2`. The elastic cluster must currently be stopped. For Linux, macOS, or Unix: ``` aws docdb-elastic start-cluster \ --cluster-arn arn:aws:docdb-elastic:us-east-1:477568257630:cluster/b9f1d489-6c3e-4764-bb42-da62ceb7bda2 ``` For Windows: ``` aws docdb-elastic start-cluster ^ --cluster-arn arn:aws:docdb-elastic:us-east-1:477568257630:cluster/b9f1d489-6c3e-4764-bb42-da62ceb7bda2 ``` ------ ## Operations you can perform on a stopped elastic cluster You can't modify the configuration of an Amazon DocumentDB elastic cluster while the cluster is stopped. You must start the cluster before performing any such administrative actions. Amazon DocumentDB applies any scheduled maintenance to your stopped elastic cluster only after it's started again. After seven days, Amazon DocumentDB automatically starts a stopped elastic cluster so that it doesn't fall too far behind in its maintenance status. When the elastic cluster restarts, you will begin to be charged for the shards in the cluster again. While an elastic cluster is stopped, Amazon DocumentDB does not perform any automated backups nor does it extend the backup retention period. # Maintaining Amazon DocumentDB elastic clusters **Topics** + [ ## Viewing pending elastic cluster maintenance actions ](#view-elastic-cluster-maintenance) + [ ## Elastic cluster engine updates ](#elastic-cluster-engine-updates) + [ ## Elastic cluster operating system updates ](#elastic-cluster-os-updates) Periodically, Amazon DocumentDB performs maintenance on Amazon DocumentDB elastic cluster resources. Maintenance most often involves updates to the database engine (elastic cluster maintenance) or the elastic cluster's underlying operating system (OS updates). Database engine updates are required patches and include security fixes, bug fixes, and enhancements to the database engine. While most operating system patches are optional, if you don't apply them for a while, the patch may be required and auto applied to maintain your security posture. So, we recommend that you apply operating system updates to your Amazon DocumentDB elastic clusters as soon as they are available. Database engine patches require that you take your Amazon DocumentDB elastic clusters offline for a short time. Once available, these patches are automatically scheduled to apply during an upcoming scheduled maintenance window of your Amazon DocumentDB elastic cluster. Elastic clusters have their own respective maintenance windows. Elastic cluster modifications that you have chosen not to apply immediately, are applied during the maintenance window. By default, when you create an elastic cluster, Amazon DocumentDB assigns a maintenance window for your elastic cluster. You can choose the maintenance window when creating an elastic cluster. You can also modify the maintenance windows at any time to fit your business schedules or practices. It is generally advised to choose maintenance windows that minimize the impact of the maintenance on your application (for example, on evenings or weekends). ## Viewing pending elastic cluster maintenance actions You can view whether a maintenance update is available for your elastic cluster by using the AWS CLI. If an update is available, you can do one of the following: + Defer a maintenance action that is currently scheduled for next maintenance window (for OS patches only). + Apply the maintenance actions immediately. + Schedule the maintenance actions to start during your next maintenance window. + Schedule the maintenance actions to start during your selected apply-on window. The maintenance window determines when pending operations start, but it does not limit the total execution time of these operations. Use the following AWS CLI operation to determine what maintenance actions are pending. List all pending maintenance actions: ``` aws docdb-elastic list-pending-maintenance-actions ``` Output from this operation looks something like the following (JSON format): ``` { 'ResourcePendingMaintenanceActions': [ { 'ResourceArn': 'string-arn', 'PendingMaintenanceActionDetails': [ { 'Action': 'ENGINE_UPDATE', 'AutoAppliedAfterDate': 'string', 'ForcedApplyDate': 'string', 'OptInStatus': 'string', 'CurrentApplyDate': 'string', 'Description': 'string' }, ] }, ], 'NextToken': 'string' } ``` Get pending maintenance action (if any) on a given `resourceArn`: ``` aws docdb-elastic get-pending-maintenance-action --resource-arn string-arn ``` Output from this operation looks something like the following (JSON format). ``` { 'ResourcePendingMaintenanceAction': { 'ResourceArn': 'string-arn', 'PendingMaintenanceActionDetails': [ { 'Action': 'ENGINE_UPDATE', 'AutoAppliedAfterDate': 'string', 'ForcedApplyDate': 'string', 'OptInStatus': 'string', 'CurrentApplyDate': 'string', 'Description': 'string' } ] } } ``` Parameters: + `ResourceArn`—The Amazon DocumentDB Amazon Resource Name (ARN) of the resource to which the pending maintenance action applies. + `Action`—The pending maintenance action being applied to the resource. Valid values: + `ENGINE_UPDATE` + `ENGINE_UPGRADE` + `SECURITY_UPDATE` + `OS_UPDATE` + `MASTER_USER_PASSWORD_UPDATE` + `AutoAppliedAfterDate`—First maintenance window after this date. `NEXT_MAINTENANCE OPT_IN` is ignored in this case. + `ForcedApplyDate`—Applied regardless of maintenance window. `IMMEDIATE OPT_IN` is ignored in this case. + `OptInStatus`—A value that specifies the type of opt-in request, or undoes an opt-in request. An opt-in request of type `IMMEDIATE` can't be undone. Valid values: + `IMMEDIATE`—Apply the maintenance action immediately. + `NEXT_MAINTENANCE`—Apply the maintenance action during the next maintenance window for the resource. + `APPLY_ON`—Apply the maintenance action on specified apply date regardless of next maintenance window for the resource. + `UNDO_OPT_IN`—Cancel any existing `NEXT_MAINTENANCE` or `APPLY_ON` opt in requests. + `CurrentApplyDate`—Displayed if opt-in-type is `APPLY_ON`. + `Description`—An option description for the maintenance action. ## Elastic cluster engine updates With Amazon DocumentDB, you can choose when to apply maintenance operations. You can decide when Amazon DocumentDB applies updates using the AWS CLI. Apply pending maintenance actions: ``` aws docdb-elastic apply-pending-maintenance-action --resource-arn string-arn --apply-action string-enum --opt-in-type string-enum [--apply-on string-date-range] ``` Parameters: + **--resource-arn**—The Amazon DocumentDB Amazon Resource Name (ARN) of the resource to which the pending maintenance action applies. + **--apply-action**—The pending maintenance action to apply to this resource. Valid values: + `ENGINE_UPDATE` + `ENGINE_UPGRADE` + `SECURITY_UPDATE` + `OS_UPDATE` + `MASTER_USER_PASSWORD_UPDATE` + **--opt-in-type**—A value that specifies the type of opt-in request, or undoes an opt-in request. An opt-in request of type `IMMEDIATE` can't be undone. Valid values: + `IMMEDIATE`—Apply the maintenance action immediately. + `NEXT_MAINTENANCE`—Apply the maintenance action during the next maintenance window for the resource. + `APPLY_ON`—Apply the maintenance action on specified apply date regardless of next maintenance window for the resource. + `UNDO_OPT_IN`—Cancel any existing `NEXT_MAINTENANCE` or `APPLY_ON` opt in requests. + **[--apply-on]**—Required if opt-in-type is `APPLY_ON`. Format: `yyyy/MM/dd HH:mm-yyyy/MM/dd HH:mm` (This option uses UTC time. The start time can be any time in the future from a minimum of 30 minutes and a maximum of 14 days, or force/apply date on pending action, whichever is earlier. Start to end time window can be a minimum of 30 minutes to a maximum of 8 hours long.) Output from this operation looks something like the following (JSON format): ``` { 'ResourcePendingMaintenanceAction': { 'ResourceArn': 'string-arn', 'PendingMaintenanceActionDetails': [ { 'Action': 'SECURITY_UPDATE', 'AutoAppliedAfterDate': 'string', 'ForcedApplyDate': 'string', 'OptInStatus': 'IMMEDIATE', 'CurrentApplyDate': 'string', 'Description': 'string' }, ] } } ``` Parameters: + `ResourceArn`—The Amazon DocumentDB Amazon Resource Name (ARN) of the resource to which the pending maintenance action applies. + `Action`—The pending maintenance action being applied to the resource. Valid values: + `ENGINE_UPDATE` + `ENGINE_UPGRADE` + `SECURITY_UPDATE` + `OS_UPDATE` + `MASTER_USER_PASSWORD_UPDATE` + `AutoAppliedAfterDate`—First maintenance window after this date. `NEXT_MAINTENANCE OPT_IN` is ignored in this case. + `ForcedApplyDate`—Applied regardless of maintenance window. `IMMEDIATE OPT_IN` is ignored in this case. + `OptInStatus`—A value that specifies the type of opt-in request, or undoes an opt-in request. An opt-in request of type `IMMEDIATE` can't be undone. Valid values: + `IMMEDIATE`—Apply the maintenance action immediately. + `NEXT_MAINTENANCE`—Apply the maintenance action during the next maintenance window for the resource. + `APPLY_ON`—Apply the maintenance action on specified apply date regardless of next maintenance window for the resource. + `UNDO_OPT_IN`—Cancel any existing `NEXT_MAINTENANCE` or `APPLY_ON` opt in requests. + `CurrentApplyDate`—Displayed if opt-in-type is `APPLY_ON`. + `Description`—An option description for the maintenance action. ### Apply dates Each maintenance action has a respective apply date that you can find when describing the pending maintenance actions. When you read the output of pending maintenance actions from the AWS CLI, three dates are listed: + `CurrentApplyDate`—The date the maintenance action will get applied either immediately or during the next maintenance window. If the maintenance is optional, this value can be null. + `ForcedApplyDate`—The date when the maintenance will be automatically applied, independent of your maintenance window. + `AutoAppliedAfterDate`—The date after which the maintenance will be applied during the cluster's maintenance window. ### User-created maintenance actions As an Amazon DocumentDBelastic cluster user, you can initiate updates to your clusters configurations. **Updating cluster primary password** ``` aws docdb-elastic update-cluster --cluster-arn string-arn [--admin-user-password string] [--auth-type string-enum] [--apply-method string-enum] [--apply-on string-date-range] #... other parameters of the API that follow here are not relevant for this configuration ``` Parameters: + **--cluster-arn**—The Amazon DocumentDB Amazon Resource Name (ARN) of the resource to which the maintenance action will be applied. + **[--admin-user-password]**—The password associated with the admin user. + **[--auth-type]**—The authentication type used to determine where to fetch the password used for accessing the elastic cluster. Valid types are `PLAIN_TEXT` or `SECRET_ARN`. + **[--apply-method]**—A value that specifies the type of method being applied. Allowed values are `IMMEDIATE` and `APPLY_ON`. Default is `IMMEDIATE`. + **[--apply-on]**—Required if `apply-method` is `APPLY_ON`. Format: `yyyy/MM/dd HH:mm-yyyy/MM/dd HH:mm` (This option uses UTC time. The start time can be any time in the future from a minimum of 30 minutes and a maximum of 14 days. Start to end time window can be a minimum of 30 minutes to a maximum of 8 hours long.) Output from this operation looks something like the following (JSON format): ``` { 'ResourcePendingMaintenanceAction': { 'ResourceArn': 'string-arn', 'PendingMaintenanceActionDetails': [ { 'Action': 'MASTER_USER_PASSWORD_UPDATE', 'OptInStatus': 'APPLY_ON', 'CurrentApplyDate': 'string', 'Description': 'string' }, ] } } ``` ### Changing your Amazon DocumentDB maintenance windows The maintenance window should fall at the time of lowest usage and thus might need changing from time to time. Your elastic cluster is unavailable during this time only if system changes (such as a scale storage operation change) are being applied and require an outage. It is unavailable only for the minimum amount of time required to make the necessary changes. The default is a 30-minute window selected at random from an 8-hour block of time for each Amazon Web Services Region, occurring on a random day of the week. To change the maintenance window, see [Modifying elastic cluster configurations](elastic-managing.md#elastic-modify). ## Elastic cluster operating system updates Amazon DocumentDB elastic clusters occasionally require operating system updates. Amazon DocumentDB upgrades the operating system to a newer version to improve database performance and customers’ overall security posture. Operating system updates don't change the cluster engine version of an Amazon DocumentDB elastic cluster. Most operating system updates for Amazon DocumentDB elastic clusters are optional and don't have a set date to apply them. However, if you don't apply these updates for a while, they may eventually become required and automatically applied during your clusters maintenance window. This is to help maintain the security posture of your database. To avoid any unexpected downtime, we recommend that you apply operating system updates to your Amazon DocumentDB elastic cluster as soon as they become available and set your cluster maintenance window at a time of your convenience as per your business needs.