Adding an Amazon DocumentDB Instance to a Cluster

You can create a new Amazon DocumentDB instance using the AWS Management Console or the AWS CLI. To add an instance to a cluster, the cluster must be in an available state. You cannot add an instance to a cluster that is stopped. If the cluster is stopped, first start the cluster, wait for the cluster to become available, and then add an instance. For more information, see Stopping and Starting an Amazon DocumentDB Cluster.

Note

If you create an Amazon DocumentDB cluster using the console, an instance is automatically created for you at the same time. If you want to create additional instances, use one of the following procedures.

Adding an Instance Using the AWS Management Console

Use the following procedure to create an instance for your cluster using the Amazon DocumentDB 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 (Adding an Instance - 图1) in the upper-left corner of the page.

  3. To choose the cluster that you want to add an instance to, select the button to the left of the cluster’s name.

  4. Choose Actions, and then choose Add instances.

  5. In the Add instance to: <cluster-name> page, repeat the following steps for each instance that you want to add to the cluster. You can have up to 15.

    1. Instance identifier — You can either enter a unique identifier for this instance or allow Amazon DocumentDB to provide the instance identifier based on the cluster identifier.

      Instance 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 instances across Amazon RDS, Neptune, and Amazon DocumentDB per AWS account, per Region.

    2. Instance class — From the drop-down list, choose the instance type you want for this instance.

    3. Promotion tier — From the drop-down list, choose the promotion tier for your instance or choose No preference to allow Amazon DocumentDB to set the promotion tier for your instance. Lower numbers mean higher priority. For more information, see Controlling the Failover Target.

    4. To add more instances, choose Add additional instances and repeat steps a, b, and c.

  6. Finish the operation.

    • To add the instances to your cluster, choose Create.

    • To cancel the operation, choose Cancel.

It takes several minutes to create an instance. You can use the console or AWS CLI to view the instance’s status. For more information, see Monitoring an Instance’s Status.

Adding an Instance Using the AWS CLI

Use the create-db-instance AWS CLI operation with the following parameters to create the primary instance for your cluster.

  • --db-instance-class — Required. The compute and memory capacity of the instance, for example, db.m4.large. Not all instance classes are available in all AWS Regions.

  • --db-instance-identifier — Required. A string that identifies the instance.

    Instance 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 instances across Amazon RDS, Neptune, and Amazon DocumentDB per AWS account, per Region.

  • --engine — Required. Must be docdb.

  • --availability-zone — Optional. The Availability Zone that you want this instance to be created in. Use this parameter to locate your instances in different Availability Zones to increase fault tolerance. For more information, see Amazon DocumentDB High Availability and Replication.

  • --promotion-tier — Optional. The failover priority tier for this instance. Must be between 0 and 15 with lower numbers being higher priority. For more information, see Controlling the Failover Target.

  1. First, determine what Availability Zones you can create your instance in.

    If you want to specify the Availability Zone before you create your instance, run the following command to determine which Availability Zones are available for your Amazon DocumentDB cluster.

    For Linux, macOS, or Unix:

    1. aws docdb describe-db-clusters \
    2.        --query 'DBClusters[*].[DBClusterIdentifier,AvailabilityZones[*]]'

    For Windows:

    1. aws docdb describe-db-clusters ^
    2.        --query 'DBClusters[*].[DBClusterIdentifier,AvailabilityZones[*]]'

    Output from this operation looks something like the following.

    1. [
    2.     [
    3.         "sample-cluster",
    4.         [
    5.             "us-east-1c",
    6.             "us-east-1b",
    7.             "us-east-1a"
    8.         ]
    9.     ]
    10. ]

  2. Second, determine what instance classes you can create in your Region.

    To determine which instance classes are available to you in your Region, run the following command. From the output, choose an instance class for the instance you want to add to your Amazon DocumentDB cluster.

    For Linux, macOS, or Unix:

    1. aws docdb describe-orderable-db-instance-options \
    2.         --engine docdb \
    3.         --query 'OrderableDBInstanceOptions[*].DBInstanceClass'

    For Windows:

    1. aws docdb describe-orderable-db-instance-options ^
    2.         --engine docdb ^
    3.         --query 'OrderableDBInstanceOptions[*].DBInstanceClass'

    Output from this operation looks something like the following.

    1. [
    2.     "db.r5.16xlarge",
    3.     "db.r5.2xlarge",
    4.     "db.r5.4xlarge",
    5.     "db.r5.8xlarge",
    6.     "db.r5.large",
    7.     "db.r5.xlarge"
    8. ]

  3. Finally, add an instance to your Amazon DocumentDB cluster.

    To add an instance to your Amazon DocumentDB cluster, run the following command..

    For Linux, macOS, or Unix:

    1. aws docdb create-db-instance \
    2.        --db-cluster-identifier sample-cluster \
    3.        --db-instance-identifier sample-instance-2 \
    4.        --availability-zone us-east-1b \
    5.        --promotion-tier 2 \
    6.        --db-instance-class db.r5.xlarge \
    7.        --engine docdb

    For Windows:

    1. aws docdb create-db-instance ^
    2.        --db-cluster-identifier sample-cluster ^
    3.        --db-instance-identifier sample-instance-2 ^
    4.        --availability-zone us-east-1b ^
    5.        --promotion-tier 2 ^
    6.        --db-instance-class db.r5.xlarge ^
    7.        --engine docdb

    Output from this operation looks something like the following.

    1. {
    2.     "DBInstance": {
    3.         "DBInstanceIdentifier": "sample-instance-2",
    4.         "DBInstanceClass": "db.r5.xlarge",
    5.         "Engine": "docdb",
    6.         "DBInstanceStatus": "creating",
    7.         "PreferredBackupWindow": "02:00-02:30",
    8.         "BackupRetentionPeriod": 1,
    9.         "VpcSecurityGroups": [
    10.             {
    11.                 "VpcSecurityGroupId": "sg-abcd0123",
    12.                 "Status": "active"
    13.             }
    14.         ],
    15.         "AvailabilityZone": "us-east-1b",
    16.         "DBSubnetGroup": {
    17.             "DBSubnetGroupName": "default",
    18.             "DBSubnetGroupDescription": "default",
    19.             "VpcId": "vpc-6242c31a",
    20.             "SubnetGroupStatus": "Complete",
    21.             "Subnets": [
    22.                 {
    23.                     "SubnetIdentifier": "subnet-abcd0123",
    24.                     "SubnetAvailabilityZone": {
    25.                         "Name": "us-west-2a"
    26.                     },
    27.                     "SubnetStatus": "Active"
    28.                 },
    29.                 {
    30.                     "SubnetIdentifier": "subnet-wxyz0123",
    31.                     "SubnetAvailabilityZone": {
    32.                         "Name": "us-west-2b"
    33.                     },
    34.                     "SubnetStatus": "Active"
    35.                 }
    36.             ]
    37.         },
    38.         "PreferredMaintenanceWindow": "sun:11:35-sun:12:05",
    39.         "PendingModifiedValues": {},
    40.         "EngineVersion": "3.6.0",
    41.         "AutoMinorVersionUpgrade": true,
    42.         "PubliclyAccessible": false,
    43.         "DBClusterIdentifier": "sample-cluster",
    44.         "StorageEncrypted": true,
    45.         "KmsKeyId": "arn:aws:kms:us-east-1:<accountID>:key/sample-key",
    46.         "DbiResourceId": "db-ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    47.         "CACertificateIdentifier": "rds-ca-2019",
    48.         "PromotionTier": 2,
    49.         "DBInstanceArn": "arn:aws:rds:us-east-1:<accountID>:db:sample-instance-2"
    50.     }
    51. }

It takes several minutes to create the instance. You can use the console or AWS CLI to view the instance’s status. For more information, see Monitoring an Amazon DocumentDB Instance’s Status.