Setting Up Step 1: Create an elastic cluster Step 2: Create an AWS Cloud9 environment Step 3: Install the mongo shell Step 4: Connect to your new elastic cluster Step 5: Shard your collection; insert and query data

Getting 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 AWS Cloud9, a web-based terminal to connect and query your elastic cluster using the mongo shell directly from the AWS Management Console.

Topics

Setting Up
Step 1: Create an elastic cluster
Step 2: Create an AWS Cloud9 environment
Step 3: Install the mongo shell
Step 4: Connect to your new elastic cluster
Step 5: Shard your collection; insert and query data

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 the Connect with EC2 instructions.

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

Open https://portal.aws.amazon.com/billing/signup.
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 an administrative 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.

In the search bar of the AWS Management Console, type in IAM and select IAM in the drop down menu.
Once you're in the IAM console, select Users from the navigation pane.
Select your username.
Click the button Add permissions.
Select Attach existing policies directly.
Type AmazonDocDBFullAccess in the search bar and select it once it appears in the search results.
Click the blue button at the bottom that says Next: Review.
Click the blue button at the bottom that says Add permissions.

Create an Amazon Virtual Private Cloud (Amazon VPC)

This step is only necessary if you don't already have a default Amazon VPC. If you don't, then complete step 1 of the Getting Started with Amazon VPC in the Amazon VPC User Guide. This will take less than five minutes.

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:

Sign into the AWS Management Console and open the Amazon DocumentDB console.
On the Amazon DocumentDB Management Console, under Clusters, choose Create.
On the Create Amazon DocumentDB cluster page, in the Cluster type section, choose Elastic Cluster.
On the Create Amazon DocumentDB cluster page, in the Configuration section, enter a unique cluster identifier (following the naming requirements below the field).
In the Shard count field, enter the number of shards you want in your cluster. The maximum number of shards per cluster is 32.

In the Shard capacity field, choose the number of virtual CPUs (vCPUs) you want associated with each shard. The maximum number of vCPUs per shard is 64. Allowed values are 2, 4, 8, 16, 32, 64.
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).
In the Authentication section, enter a string that identifies the the login name of the master user in the Username field.

In the Password field, enter a unique password that complies with the instructions.
In the Encryption section, keep the default settings.

Optionally, you can enter a AWS KMS key ARN you created. For more information, see Elastic cluster data encryption.

Important
Encryption must be enabled for elastic clusters.
In the Maintenance section, choose the day, time, and duration when modifications or patches are applied to your cluster.
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 both the cluster and instance status show as Available 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—Optional. The number of vCPUs assigned to each shard. Maximum is 64. Allowed values are 2, 4, 8, 16, 32, 64.
--shard-count—Optional. The number of shards assigned to the cluster. Maximum is 32.
--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.
--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 \
     --auth-type SECRET_ARN \
     --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

For Windows:


aws docdb-elastic create-cluster ^
     --cluster-name sample-cluster-123 ^
     --shard-capacity 8 ^
     --shard-count 4 ^
     --auth-type SECRET_ARN ^
     --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

Step 2: Create an AWS Cloud9 environment

AWS Cloud9 provides a web-based terminal that you can use to connect to and query your Amazon DocumentDB elastic clusters using the mongo shell.

Note

Note: Your AWS Cloud9 environment must be in the same security group as your instance. You can change the security group in the Amazon EC2 console.

Use your AWS account and access the AWS Management Console.
Navigate to the AWS Cloud9 Console. You can type "Cloud9" in the Search field to locate it.
On the AWS Cloud9 environment home page, choose Create environment.
On the Name environment page, in the Name field, enter a name of your choosing.

Choose Next step.
In Environment settings under the Environment type section, select, Create a new EC2 instance for environment (direct access).

Under the Instance type section, select an appropriate instance type for your network.

Under the Platform section, select Amazon Linux 2 (recommended).
Expand Network settings (advanced).

Choose the VPC and one of the subnets that you used when creating your elastic cluster.

Choose Next step.
Review your AWS Cloud9 configuration.

If your configuration is correct, choose Create environment.

Step 3: Install the mongo shell

Once yours AWS Cloud9 environment is ready, you are ready to connect to your cluster. Next, install the mongo shell in your AWS Cloud9 environment that you created in Step 3. The mongo shell is a command-line utility that you use to connect and query your elastic cluster.

If your AWS Cloud9 environment is still open from Step 3, go back to that environment and skip to instruction 3. If you navigated away from you AWS Cloud9 environment, in the AWS Cloud9 console, under Your environments, find the environment labeled with the name you set in the previous step. Choose Open IDE.

At the command prompt, create the repository file with the following command:


echo -e "[mongodb-org-4.0] \nname=MongoDB Repository\nbaseurl=https://repo.mongodb.org/yum/amazon/2013.03/mongodb-org/4.0/x86_64/\ngpgcheck=1 \nenabled=1 \ngpgkey=https://www.mongodb.org/static/pgp/server-4.0.asc" | sudo tee /etc/yum.repos.d/mongodb-org-4.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 4.

On the Amazon DocumentDB Management Console, under Clusters, locate your cluster. Sort by role to display all clusters with the role Elastic Cluster.
Choose the cluster you created by selecting the cluster identifier. From Connectivity and Security, copy your endpoint and paste it into your AWS Cloud9 environment.
Once connected, you should see 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.

To shard a collection, enter the following:

sh.shardCollection("db.Employee1" , { "Employeeid" : "hashed" })
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 })
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
}
```

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 ] }

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

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

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 }

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

How it works

Best Practices