Amazon DocumentDB
Developer Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Step 1: Create an Amazon DocumentDB Cluster

In this step, you create an Amazon DocumentDB cluster in your default Amazon Virtual Private Cloud (Amazon VPC) using the AWS Management Console.

Using the AWS Management Console

The following steps walk you through the basics of creating an Amazon DocumentDB cluster with one or more instances. In these steps, you name your cluster, choose the instance class, and specify the number of instances. You also provide a user name and password that are used to authenticate access to your cluster. Beyond that, this procedure uses the default values for the cluster's Amazon VPC, port (27017), encryption at rest (enabled), and windows for backups and maintenance. If you prefer to set your own values for these instead of using the default values, follow the procedure at Creating an Amazon DocumentDB Cluster.

To create a cluster and add instances to it using the AWS CLI, see both of the following topics:

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.

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

  3. In the navigation pane, choose Clusters, and then choose Create.

    Tip

    If you do not see the navigation pane on the left side of your screen, choose the menu icon () in the upper-left corner of the page.

  4. On the Create Amazon DocumentDB cluster page, complete the Configuration pane.

    
            Screenshot: Create Amazon DocumentDB Cluster screen, 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, Amazon Neptune, and Amazon DocumentDB) per AWS account, per Region.

    2. Instance class—Accept the default db.r5.large, or choose the instance class that you want from the list.

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

  5. Complete the Authentication pane.

    
            Screenshot: Create Amazon DocumentDB Cluster screen, Authentication pane.
    1. Master username—Enter a name for the master user.

      Master User Naming Constraints:
      • Length is [1-63] alphanumeric characters.

      • First character must be a letter.

      • Cannot be a word reserved by the database engine.

      To log in to your cluster, you must use the master user name.

    2. Master password—Enter a password for the master user, and then confirm it.

      Master 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)

      To log in to your cluster, you must use the master password.

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

      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.

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

    2. In the Resources section of the main window, choose Security groups.

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

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

      2. Protocol—From the list, choose the type of protocol.

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

      4. 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).

      5. Description—Enter a description for this rule.

      6. When finished creating the rule, choose Save.

Note

You can access the Amazon DocumentDB cluster when the instance status for a given cluster is available. This can take several minutes. To monitor an instance's status, see Monitoring an Amazon DocumentDB Instance's Status.

While your Amazon DocumentDB cluster is being created, you can proceed to Step 2: Launch an Amazon EC2 Instance and follow the instructions there.

Using the AWS CLI

If you haven't already done so, go to http://aws.amazon.com/cli and download the AWS CLI. After you download it, follow the instructions for Installing the AWS CLI and Configuring the AWS CLI in the AWS Command Line Interface User Guide.

When you create an Amazon DocumentDB cluster using the AWS CLI, you first create the cluster then create instances for the cluster. To create the cluster, use the create-db-cluster operation with the following parameters.

  • --db-cluster-identifier—Required. The name for the cluster.

  • --engine—Required. Must be docdb.

  • --master-username—Required. The user defined username for accessing this cluster.

  • --master-user-password—Required. The password for the user to access this cluster.

  • For optional parameters, see CreateDBCluster in the Amazon DocumentDB API Reference.

To create a cluster

  • Create a new Amazon DocumentDB cluster:

    aws docdb create-db-cluster \ --db-cluster-identifier sample-cluster \ --engine docdb \ --master-username yourMasterUsername \ --master-user-password yourMasterPassword
    1. Replace sample-cluster with the name that you want for your new 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, Amazon Neptune, and Amazon DocumentDB) per AWS account, per Region.

    2. Replace yourMasterUsername with your master user name.

      Master User Naming Constraints:
      • Length is [1-63] alphanumeric characters.

      • First character must be a letter.

      • Cannot be a word reserved by the database engine.

    3. Replace yourMasterPassword with your master password.

      Master 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)

    Note

    To log in to your cluster, you must use the master user name and master password.

    If you want to configure your cluster beyond what is done here, see Creating an Amazon DocumentDB Cluster.

Now create one or more instances for your cluster. To create an instance, use the create-db-instance operation with the following parameters.

  • --db-cluster-identifier—Required. The name of the cluster you want this instance to be part of.

  • --db-instance-class—Required. The compute and memory class you want for this instance. Example db.r5.large.

  • --db-instance-identifier—Required. The name of this 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, Amazon Neptune, and Amazon DocumentDB) per AWS account, per Region.

  • --engine—Required. Must be docdb.

  • For optional parameters, see CreateDBInstance in the Amazon DocumentDB API Reference.

To create an instance for the cluster

  1. Add an instance to the Amazon DocumentDB cluster:

    aws docdb create-db-instance \ --db-cluster-identifier sample-cluster \ --db-instance-identifier sample-instance \ --db-instance-class db.r5.large \ --engine docdb

    This instance (sample-instance) is the primary instance. If you create additional instances, they are the read replica instances. For more information, see Adding an Amazon DocumentDB Instance to a Cluster.

  2. It takes several minutes to create the cluster and the instances. You can use the AWS CLI to monitor the progress of these actions.

    1. To view the status of the Amazon DocumentDB cluster:

      aws docdb describe-db-clusters \ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].[DBClusterIdentifier,Status]'

      Output from this operation looks something like the following (JSON format).

      [ [ "sample-cluster", "available" ] ]
    2. To view the status of the Amazon DocumentDB instance:

      aws docdb describe-db-instances \ --db-instance-identifier sample-instance \ --query 'DBInstances[*].[DBInstanceIdentifier,DBInstanceStatus]'

    Note

    You can access Amazon DocumentDB when the status for a given cluster is available. This can take several minutes.

  3. While your Amazon DocumentDB cluster is being created, proceed to Step 2: Launch an Amazon EC2 Instance and follow the instructions there.