Connect Using Amazon EC2

Connect Using Amazon EC2

This section describes how to launch an Amazon DocumentDB (with MongoDB compatibility) cluster using Amazon EC2 and interact with it, using the mongo shell. The video below demonstrates the steps in this guide.

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.

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 in Amazon DocumentDB.

In the search bar of the AWS Management Console, type in IAM and select IAM in the drop down menu that appears.
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)

Depending on which AWS region you are in, you may or may not have a default VPC already created. If you don’t have a default VPC, 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 Amazon EC2 Instance

In this step, you will create an Amazon EC2 instance in the same Region and Amazon VPC that you will later use to provision your Amazon DocumentDB cluster.

On the Amazon EC2 console, choose Launch instance.
Locate Amazon Linux 2 AMI and choose Select.
Choose the t3.micro instance type.
Choose Review and Launch, which will allow you to skip to the console’s Step 7: Review Instance Launch page.
Under Security Groups, choose Edit security groups.
This will default to Create a new security group. In the Security group name field, write demoEC2.
Change Type to SSH. This will automatically set the port range to 22.
Select the drop down menu for Source and choose My IP.

Note

You can only access the demoEC2 security group from your current IP address. If your IP address changes, you must update the security group.
Now choose Review and Launch. You should now see the demoEC2 security group in the Security Groups section.
Verify the information and choose Launch.
A window will pop up titled Select an existing key pair or create a new key pair. It will look like this:

You must provide an Amazon EC2 key pair. If you do have an Amazon EC2 key pair:
1. Select a key pair, choose your key pair from the list.
2. You must already have the private key file (.pem file) available to log in to your Amazon EC2 instance.
If you do not have an Amazon EC2 key pair:
1. Choose Create a new key pair.
2. Write a name for the key bar in the field Key pair name.
3. Download the private key file (.pem file). You need this file later when you log in to your Amazon EC2 instance.
Choose Launch Instances.

Step 2: Create a security group

You will now create a new security group in your default Amazon VPC. The security group demoDocDB enables you to connect to your Amazon DocumentDB cluster on port 27017 (the default port for Amazon DocumentDB) from your Amazon EC2 instance.

On the Amazon EC2 console, under Network and Security, choose Security groups.
Choose Create security group.
For Security group name, enter demoDocDB.
For Description, enter a description.
For VPC, accept the usage of your default VPC.
In the Inbound rules section, choose Add rule.
For Type, choose Custom TCP Rule.
For Port range, enter 27017.
For Destination, choose Custom. In the field next to it, search for the security group you just made called demoEC2. You may need to refresh your browser for the Amazon EC2 console to auto-populate the demoEC2 source name.
Accept all other defaults and choose Create security group.

Step 3: Create an Amazon DocumentDB Cluster

While the Amazon EC2 instance is being provisioned, you will create your Amazon DocumentDB cluster.

Navigate to the Amazon DocumentDB console and choose Clusters from the navigation pane.
Choose Create.
For Number of instances, choose 1. This will minimize cost. Leave other settings at their default.
For Authentication, enter a username and password. Important: You will need this username and password to authenticate your cluster in a later step.
Turn on Show advanced settings.
In the Network settings section, for Amazon VPC security groups, choose demoDocDB.
Choose Create cluster.

Step 4: Connect to your Amazon EC2 instance

To install the mongo shell, you must first connect to your Amazon EC2 instance. Installing the mongo shell enables you to connect to and query your Amazon DocumentDB cluster. Complete the following steps:

On the Amazon EC2 console, navigate to your instances and see if the instance you just created is running. If it is, select the instance.
Choose Connect.
You will see three options for your connection method: Amazon EC2 Instance Connect, Session Manager, or SSH client. You must choose one and follow its instructions.

Note

If your IP address changed after you started this walkthrough, or you are coming back to your environment at a later time, you must update your demoEC2 security group inbound rule to enable inbound traffic from your new API address.

Step 5: Install the mongo shell

You can now install the mongo shell, which is a command-line utility that you use to connect and query your Amazon DocumentDB cluster. Follow the instructions below to install the mongo shell for your operating system.

To install the mongo shell on Amazon Linux

Create the repository file. At the command line of your EC2 instance, execute the follow command:

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

When it is complete, install the mongo shell by executing the following command:
```
sudo yum install -y mongodb-org-shell
```

To install the mongo shell on Ubuntu 18.04

Import the public key that will be used by the package management system.

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 2930ADAE8CAF5059EE73BB4B58712A2291FA4AD5

Create the list file /etc/apt/sources.list.d/mongodb-org-3.6.list for MongoDB using the command appropriate for your version of Ubuntu.

Ubuntu 18.04
```
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu xenial/mongodb-org/3.6 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-3.6.list
```
Note

The command above will install the mongo 3.6 shell for both Bionic and Xenial.
Reload the local package database using the following command:
```
sudo apt-get update
```

Install the MongoDB shell.

sudo apt-get install -y mongodb-org-shell

For information about installing earlier versions of MongoDB on your Ubuntu system, see Install MongoDB Community Edition on Ubuntu.

To install the mongo shell on other operating systems, see Install MongoDB Community Edition in the MongoDB documentation.

Step 6: Manage Amazon DocumentDB TLS

Download the CA certificate for Amazon DocumentDB with the following code: wget https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem

Note

Transport Layer Security (TLS) is enabled by default for any new Amazon DocumentDB clusters. For more information, see Managing Amazon DocumentDB Cluster TLS Settings.

Step 7: Connect to your Amazon DocumentDB cluster

On the Amazon Document DB console, under Clusters, locate your cluster. Choose the cluster you created.
Navigate to the Connection box. It will look like this.

Copy the connection string provided.

After you paste it into your terminal and make the following changes to it: first, make sure you have the correct username in the string. Then, omit <insertYourPassword> so that you are prompted for the password by the mongo shell when you connect. Your connection string should look similar to the following:

mongo --ssl host docdb-2020-02-08-14-15-11. cluster.region.docdb.amazonaws.com:27107 --sslCAFile rds-combined-ca-bundle.pem --username demoUser --password
Now press enter in your terminal. You will now be prompted for your password. Enter your password.
When you enter your password and can see the rs0:PRIMARY> prompt, you are successfully connected to your Amazon DocumentDB cluster.

Having problems connecting? See Troubleshooting Amazon DocumentDB.

Step 8: Insert and query data

Now that you are connected to your cluster, you can run a few queries to get familiar with using a document database.

To insert a single document, enter the following:
```
db.collection.insert({"hello":"DocumentDB"})
```
You get the following output:

WriteResult({ "nInserted" : 1 })
You can read the document that you wrote with the findOne() command (because it only returns a single document). Input the following:
```
db.collection.findOne()
```
You get the following output:

{ "_id" : ObjectId("5e401fe56056fda7321fbd67"), "hello" : "DocumentDB" }

To perform a few more queries, consider a gaming profiles use case. First, insert a few entries into a collection titled profiles. Input the following:

db.profiles.insertMany([
            { "_id" : 1, "name" : "Matt", "status": "active", "level": 12, "score":202},
            { "_id" : 2, "name" : "Frank", "status": "inactive", "level": 2, "score":9},
            { "_id" : 3, "name" : "Karen", "status": "active", "level": 7, "score":87},
            { "_id" : 4, "name" : "Katie", "status": "active", "level": 3, "score":27}
            ])

You get the following output:

{ "acknowledged" : true, "insertedIds" : [ 1, 2, 3, 4 ] }
Use the find() command to return all the documents in the profiles collection. Input the following:
```
db.profiles.find()
```
You will get an output that will match the data you typed in Step 5.
Use a query for a single document using a filter. Input the following:
```
db.profiles.find({name: "Katie"})
```
You should get back this output:

{ "_id" : 4, "name" : "Katie", "status": "active", "level": 3, "score":27}

Now let’s try to find a profile and modify it using the findAndModify command. We’ll give the user Matt an extra ten points with the following code:


   db.profiles.findAndModify({
       query: { name: "Matt", status: "active"},
       update: { $inc: { score: 10 } }
   })

You get the following output (note that his score hasn’t increased yet):


   {
   "_id" : 1,
   "name" : "Matt",
   "status" : "active",
   "level" : 12,
   "score" : 202
   }

You can verify that his score has changed with the following query:

db.profiles.find({name: "Matt"})
You get the following output:

{ "_id" : 1, "name" : "Matt", "status" : "active", "level" : 12, "score" : 212 }

Step 9: Explore

Congratulations! You have successfully completed the Quick Start Guide to Amazon DocumentDB.

What’s next? Learn how to fully leverage this powerful database with some of its popular features:

Note

To save on cost, you can either stop your Amazon DocumentDB cluster to reduce costs or delete the cluster. By default, after 30 minutes of inactivity, your AWS Cloud9 environment will stop the underlying Amazon EC2 instance.