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:

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.

  2. 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 (Describing Clusters - 图1) in the upper-left corner of the page.

  3. 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.

    • 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 DescribeDBClusters 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 1: List all Amazon DocumentDB clusters

The following AWS CLI code lists the details for all Amazon DocumentDB clusters in a region.

  1. aws docdb describe-db-clusters --filter Name=engine,Values=docdb

Output from this operation looks something like the following.

  1. {
  2.     "DBClusters": [
  3.         {
  4.             "AvailabilityZones": [
  5.                 "us-east-1c",
  6.                 "us-east-1b",
  7.                 "us-east-1a"
  8.             ],
  9.             "BackupRetentionPeriod": 1,
  10.             "DBClusterIdentifier": "sample-cluster-1",
  11.             "DBClusterParameterGroup": "sample-parameter-group",
  12.             "DBSubnetGroup": "default",
  13.             "Status": "available",
  14.             ...
  15.         },
  16.         {
  17.             "AvailabilityZones": [
  18.                 "us-east-1c",
  19.                 "us-east-1b",
  20.                 "us-east-1a"
  21.             ],
  22.             "BackupRetentionPeriod": 1,
  23.             "DBClusterIdentifier": "sample-cluster-2",
  24.             "DBClusterParameterGroup": "sample-parameter-group",
  25.             "DBSubnetGroup": "default",
  26.             "Status": "available",
  27.             ...
  28.         },
  29.         {
  30.             "AvailabilityZones": [
  31.                 "us-east-1c",
  32.                 "us-east-1b",
  33.                 "us-east-1a"
  34.             ],
  35.             "BackupRetentionPeriod": 1,
  36.             "DBClusterIdentifier": "sample-cluster-3",
  37.             "DBClusterParameterGroup": "sample-parameter-group",
  38.             "DBSubnetGroup": "default",
  39.             "Status": "available",
  40.             ...
  41.         }
  42.     ]
  43. }

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:

  1. aws docdb describe-db-clusters \
  2.    --filter Name=engine,Values=docdb \
  3.    --db-cluster-identifier sample-cluster

For Windows:

  1. aws docdb describe-db-clusters ^
  2.    --filter Name=engine,Values=docdb ^
  3.    --db-cluster-identifier sample-cluster

Output from this operation looks something like the following.

  1. {
  2.     "DBClusters": [
  3.         {
  4.             "AvailabilityZones": [
  5.                 "us-east-1c",
  6.                 "us-east-1b",
  7.                 "us-east-1a"
  8.             ],
  9.             "BackupRetentionPeriod": 1,
  10.             "DBClusterIdentifier": "sample-cluster",
  11.             "DBClusterParameterGroup": "sample-parameter-group",
  12.             "DBSubnetGroup": "default",
  13.             "Status": "available",
  14.             "EarliestRestorableTime": "2020-03-09T00:04:26.844Z",
  15.             "Endpoint": "sample-cluster.node.us-east-1.docdb.amazonaws.com",
  16.             "ReaderEndpoint": "sample-cluster.node.us-east-1.docdb.amazonaws.com",
  17.             "MultiAZ": false,
  18.             "Engine": "docdb",
  19.             "EngineVersion": "4.0.0",
  20.             "LatestRestorableTime": "2020-03-10T20:38:17.456Z",
  21.             "Port": 27017,
  22.             "MasterUsername": "<user-name>",
  23.             "PreferredBackupWindow": "00:00-00:30",
  24.             "PreferredMaintenanceWindow": "tue:09:50-tue:10:20",
  25.             "DBClusterMembers": [
  26.                 {
  27.                     "DBInstanceIdentifier": "sample-instance-1",
  28.                     "IsClusterWriter": true,
  29.                     "DBClusterParameterGroupStatus": "in-sync",
  30.                     "PromotionTier": 1
  31.                 },
  32.                 {
  33.                     "DBInstanceIdentifier": "sample-instance-2",
  34.                     "IsClusterWriter": false,
  35.                     "DBClusterParameterGroupStatus": "in-sync",
  36.                     "PromotionTier": 1
  37.                 },
  38.             ],
  39.             "VpcSecurityGroups": [
  40.                 {                             
  41.                     "VpcSecurityGroupId": "sg-abcd0123",
  42.                     "Status": "active"
  43.                 }
  44.             ],
  45.             "HostedZoneId": "ABCDEFGHIJKLMN",
  46.             "StorageEncrypted": true,
  47.             "KmsKeyId": "arn:aws:kms:us-east-1:123456789012:key/wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  48.             "DbClusterResourceId": "cluster-ABCDEFGHIJKLMNOPQRSTUVWXYZ",
  49.             "DBClusterArn": "arn:aws:rds:us-east-1:123456789012:cluster:sample-cluster",
  50.             "AssociatedRoles": [],
  51.             "ClusterCreateTime": "2020-01-10T22:13:38.261Z",
  52.             "EnabledCloudwatchLogsExports": [
  53.                 "profiler"
  54.             ],
  55.             "DeletionProtection": true
  56.         }
  57.     ]
  58. }

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 in the AWS Command Line Interface User Guide.

The following example lists the instances in an Amazon DocumentDB cluster.

For Linux, macOS, or Unix:

  1. aws docdb describe-db-clusters \
  2.     --filter Name=engine,Values=docdb \
  3.     --db-cluster-identifier sample-cluster \
  4.     --query 'DBClusters[*].[DBClusterMembers]'

For Windows:

  1. aws docdb describe-db-clusters ^
  2.     --filter Name=engine,Values=docdb ^
  3.     --db-cluster-identifier sample-cluster ^
  4.     --query 'DBClusters[*].[DBClusterMembers]'

Output from this operation looks something like the following.

  1. [
  2.     [
  3.         [
  4.             {
  5.                 "DBInstanceIdentifier": "sample-instance-1",
  6.                 "IsClusterWriter": true,
  7.                 "DBClusterParameterGroupStatus": "in-sync",
  8.                 "PromotionTier": 1
  9.             },
  10.             {
  11.                 "DBInstanceIdentifier": "sample-instance-2",
  12.                 "IsClusterWriter": false,
  13.                 "DBClusterParameterGroupStatus": "in-sync",
  14.                 "PromotionTier": 1
  15.             }
  16.         ]
  17.     ]
  18. ]