Get started with Amazon DocumentDB elastic clusters

This getting started section walks you through on how you can create and query your first elastic cluster. There are many ways to connect and get started with elastic clusters. This guide uses Amazon Elastic Compute Cloud (Amazon EC2) to connect and query your Amazon DocumentDB elastic cluster directly from the AWS Management Console.

Setting Up

If you would rather connect to your Amazon DocumentDB from your local machine by creating an SSH connection to an Amazon EC2 instance, please see Connecting with Amazon EC2.

Prerequisites

Before you create your first Amazon DocumentDB cluster, you must do the following:

Create an Amazon Web Services (AWS) account

Before you can begin using Amazon DocumentDB, you must have an Amazon Web Services (AWS) account. The AWS account is free. You pay only for the services and resources that you use.

If you do not have an AWS account, complete the following steps to create one.

To sign up for an AWS account

1. Open https://portal.aws.amazon.com/billing/signup.

2. Follow the online instructions.

   Part of the sign-up procedure involves receiving a phone call and entering a verification code on the phone keypad.

   When you sign up for an AWS account, an AWS account root user is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform tasks that require root user access.

Set up the needed AWS Identity and Access Management (IAM) permissions.

Access to manage Amazon DocumentDB resources such as clusters, instances, and cluster parameter groups requires credentials that AWS can use to authenticate your requests. For more information, see Identity and Access Management for Amazon DocumentDB.

1. In the search bar of the AWS Management Console, type in IAM and select IAM in the drop down menu.

2. Once you're in the IAM console, select Users from the navigation pane.

3. Select your username.

4. Click the button Add permissions.

5. Select Attach policies directly.

6. Type AmazonDocDBFullAccess in the search bar and select it once it appears in the search results.

7. Click the Next button.

8. Click the Add permissions button.

Create an Amazon Virtual Private Cloud (Amazon VPC)

Your AWS account includes a default VPC in each region. This step is only necessary if you choose to use a default Amazon VPC. In this case, complete the steps in the Create a Amazon VPC topic in the Amazon VPC User Guide.

Launch an Amazon EC2 instance

Complete steps 1 and 2 of the Get started with Amazon EC2 topic in the Amazon Elastic Compute Cloud User Guide.

Note

Record the name and ID of the security group created for your Amazon EC2 instance.

Step 1: Create an elastic cluster

In this section we explain how to create a brand new elastic cluster, using either the AWS Management Console or AWS CLI with the following instructions.

Using the AWS Management Console

To create an elastic cluster configuration using the AWS Management Console:

1. Sign into the AWS Management Console and open the Amazon DocumentDB console.

2. On the Amazon DocumentDB Management Console, under Clusters, choose Create.

   

3. On the Create Amazon DocumentDB cluster page, in the Cluster type section, choose Elastic Cluster.

   

4. On the Create Amazon DocumentDB cluster page, in the Configuration section, enter a unique cluster identifier (following the naming requirements below the field).

   

5. For the shard configuration fields:

   1. In the Shard count field, enter the number of shards you want in your cluster. The maximum number of shards per cluster is 32.

      Note

      Two nodes will be deployed for each shard. Both nodes will have the same shard capacity.

   2. In the Shard instance count field, choose the number of replica instances you want associated with each shard. The maximum number of shard instances is 16, in increments of 1. All replica instances have the same shard capacity as defined in the following field.

      Note

      The number of replica instances applies to all shards in the elastic cluster. A shard instance count value of 1 means there is one writer instance, and any additional instances are replicas that can be used for reads and to improve availability.

   3. In the Shard capacity field, choose the number of virtual CPUs (vCPUs) you want associated with each shard instance. The maximum number of vCPUs per shard instance is 64. Allowed values are 2, 4, 8, 16, 32, 64.

   

6. In the Virtual Private Cloud (VPC) field, choose a VPC from the drop-down list.

   For Subnets and VPC security groups, you can use the defaults or select three subnets of your choice and up to three VPC security groups (minimum one).

   

7. In the Authentication section, enter a string that identifies the the login name of the primary user in the Username field.

   In the Password field, enter a unique password that complies with the instructions.

   

8. In the Encryption section, keep the default settings.

   Optionally, you can enter a AWS KMS key ARN you created. For more information, see Data encryption at rest for Amazon DocumentDB elastic clusters.

   Important

   Encryption must be enabled for elastic clusters.

9. In the Backup section, edit the fields according to your backup requirements.

   

   1. Backup retention period—In the list, choose the number of days to keep automatic backups of this cluster before deleting them.

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

      2. Choose No preference if you want Amazon DocumentDB to choose the time and duration when backups are created.

10. In the Maintenance section, choose the day, time, and duration when modifications or patches are applied to your cluster.

    

11. Choose Create cluster.

The elastic cluster is now provisioning. This can take up to a few minutes to finish. You can connect to your cluster when the elastic cluster status shows as active in the Clusters list.

Using the AWS CLI

To create an elastic cluster using the AWS CLI, use the create-cluster operation with the following parameters:

• --cluster-name—Required. The current name of the elastic scale cluster as entered during creation or last modified.

• --shard-capacity—Required. The number of vCPUs assigned to each shard. Maximum is 64. Allowed values are 2, 4, 8, 16, 32, 64.

• --shard-count—Required. 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.

• --admin-user-name—Required. The username associated with the admin user.

• --admin-user-password—Required. The password associated with the admin user.

• --auth-type—Required. 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.

• --vpc-security-group-ids—Optional. Configure a list of EC2 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.

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

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

• --backup-retention-period—Optional. The number of days for which automated backups are retained. The default value is 1.

• --storage-encrypted—Optional. Configues whether the cluster is encrypted or not encrypted.

  --no-storage-encrypted specifies that the cluster is not encrypted.

• --subnet-ids—Optional. Configure network subnet Ids.

In the following example, replace each user input placeholder with your own information.

Note

The following examples include creation of a specific KMS key. To use the default KMS key, do not include the --kms-key-id parameter.

For Linux, macOS, or Unix:

aws docdb-elastic create-cluster \
     --cluster-name sample-cluster-123 \
     --shard-capacity 8 \
     --shard-count 4 \
     --shard-instance-count 3 \
     --auth-type PLAIN_TEXT \
     --admin-user-name testadmin \
     --admin-user-password testPassword \
     --vpc-security-group-ids 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 \
     --preferred-backup-window 18:00-18:30 \ 
     --backup-retention-period 7

For Windows:

aws docdb-elastic create-cluster ^
     --cluster-name sample-cluster-123 ^
     --shard-capacity 8 ^
     --shard-count 4 ^
     --shard-instance-count 3 ^
     --auth-type PLAIN_TEXT ^
     --admin-user-name testadmin ^
     --admin-user-password testPassword ^
     --vpc-security-group-ids 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 \
     --preferred-backup-window 18:00-18:30 \ 
     --backup-retention-period 7

Step 2: Enable inbound connections

Access to an Amazon DocumentDB cluster is controlled by it’s associated security group. In this step you will modify the Amazon DocumentDB security group to allow communication from the Amazon EC2 instance through the port that’s configured with the elastic cluster (default 27017).

1. On the Amazon DocumentDB management console, under Clusters, locate your cluster.

   1. Choose the cluster you created by clicking on the cluster identifier.

   2. In the Connectivity & security tab, in the Security section, choose VPC Security Groups.

      This opens the Amazon EC2 management console Security Groups list. Alternatively, you can access the Amazon EC2 management console, select Security Groups from the Network and Security section.

   3. Choose the Amazon DocumentDB (default) security group.

   

2. Choose the Inbound rules tab (you may need to scroll to the bottom of the window), then choose Edit inbound rules.

   

3. In the Edit inbound rules dialog, select Add rule.

   1. For Port range, enter 27017.

   2. Leave Source as Custom and search for the security group value you recorded from your EC2 instance you created in Prerequisites.

   3. Choose Save rules.

   

Step 3: Install the mongo shell

Install the mongo shell in your Amazon EC2 instance that you created in Prerequisites. The mongo shell is a command-line utility that you use to connect and query your elastic cluster.

Connect to your Amazon EC2 instance and at the command prompt, create the repository file with the following command:

echo -e "[mongodb-org-5.0] \nname=MongoDB Repository\nbaseurl=https://repo.mongodb.org/yum/amazon/2023/mongodb-org/5.0/x86_64/\ngpgcheck=1 \nenabled=1 \ngpgkey=https://pgp.mongodb.com/server-5.0.asc" | sudo tee /etc/yum.repos.d/mongodb-org-5.0.repo

When it is complete, install the mongo shell with the following command:

sudo yum install -y mongodb-org-shell

Step 4: Connect to your new elastic cluster

Connect to your cluster using the mongo shell that you installed in Step 2.

1. On the Amazon DocumentDB Management Console, under Clusters, locate your cluster. Sort by role to display all clusters with the role Elastic Cluster.

   

2. Choose the cluster you created by selecting the cluster identifier. From Connectivity and Security, copy your endpoint and paste it into your Amazon EC2 instance.

   

3. Once connected, you should see something similar to the following output:

   

Step 5: Shard your collection; insert and query data

Elastic clusters add support for sharding in Amazon DocumentDB. Now that you are connected to your cluster, you can shard the cluster, insert data and run a few queries.

1. To shard a collection, enter the following:

   sh.shardCollection("db.Employee1" , { "Employeeid" : "hashed" })

2. To insert a single document, enter the following:

   db.Employee1.insert({"Employeeid":1, "Name":"Joe", "LastName": "Bruin", "level": 1 })

   The following output is displayed:

   WriteResult({ "nInserted" : 1 })

3. To read the document that you wrote, enter the findOne() command (it returns a single document):

   db.Employee1.findOne()

   The following output is displayed:

   {
   "_id" : ObjectId("61f344e0594fe1a1685a8151"),
   "EmployeeID" : 1,
   "Name" : "Joe",
   "LastName" : "Bruin",
   "level" : 1
   }

4. To perform a few more queries, consider a gaming profile use case. First, insert a few entries into a collection titled "Employee". Enter the following:

   db.Employee1.insertMany([
       { "Employeeid" : 1, "name" : "Matt", "lastname": "Winkle", "level": 12},
       { "Employeeid" : 2, "name" : "Frank", "lastname": "Chen", "level": 2},
       { "Employeeid" : 3, "name" : "Karen", "lastname": "William", "level": 7},
       { "Employeeid" : 4, "name" : "Katie", "lastname": "Schaper", "level": 3}
   ])

   The following output is displayed:

   { "acknowledged" : true, "insertedIds" : [ 1, 2, 3, 4 ] }

5. To return all the documents in the profiles collection, enter the find() command:

   db.Employee1.find()

   The data you entered in step 4 is displayed.

6. To query a single document, include a filter (for example: "Katie"). Enter the following:

   db.Employee1.find({name: "Katie"})

   The following output is displayed:

   { "_id" : 4, "name" : "Katie", "lastname": "Schaper", "level": 3}

7. To find a profile and modify it, enter the findAndModify command. In this example, the employee "Matt" is given a higher level of "14":

   db.Employee1.findAndModify({     
       query: { "Employeeid" : 1, "name" : "Matt"},     
       update: { "Employeeid" : 1, "name" : "Matt", "lastname" : "Winkle", "level" : 14 } 
   })

   The following output is displayed (note that the level has not changed yet):

   {
       "_id" : 1,
       "name" : "Matt",
       "lastname" : "Winkle",
       "level" : 12,
   }

8. To verify the level increase, enter the following query:

   db.Employee1.find({name: "Matt"})

   The following output is displayed:

   { "_id" : 1, "name" : "Matt", "lastname" : "winkle", "level" : 14 }