Amazon DocumentDB
Developer Guide

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

  2. If you want to create your cluster in an AWS Region other than the US East (N. Virginia) Region, choose the Region in the upper-right section of the console.

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

  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–16] 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.


        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.

      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 an Amazon DocumentDB 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 27107 (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

    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: 27107).

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

      5. Description—Enter a description for this rule.

      6. When finished creating the rule, choose Save.


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.