Connect Amazon EC2 manually

The following steps assume you have completed the steps in the Prerequisites topic.

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.

1. On the Amazon EC2 console, choose Launch instance.

   

2. Enter a name or identifier in the Name field located in the Name and tags section.

3. In the Amazon Machine Image (AMI) drop-down list, locate Amazon Linux 2 AMI and choose it.

   

4. Locate and choose t3.micro in the Instance type drop-down list.

   

5. In the Key pair (login) section, enter the identifier of an existing key-pair, or choose Create new key pair.

   

   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 or .ppk file) available to log in to your Amazon EC2 instance.

   If you do not have an Amazon EC2 key pair:

   1. Choose Create new key pair, the Create key pair dialog box appears.

   2. Enter a name in the Key pair name field.

   3. Choose the Key pair type and Private key file format.

   4. Choose Create key pair.

   

   Note

   For security purposes, we highly recommand using a key-pair for both SSH and internet connectivity to your EC2 instance.

6. In the Network seetings section, under Firewall (security groups), choose either Create security group or Select existing security group.

   

   If you chose to select an existing security group, select one from the Common security groupsdrop-down list.

   If you chose to create a new security group, perform the following:

   1. Check all the traffic allow rules that apply to your EC2 connectivity.

   2. In the IP field, choose My IP or select Custom to choose from a list of CIDR blocks, prefix lists, or securioty groups. We do not recommend Anywhere as a choice, unless your EC2 instance is on an isolated network, because it allows any IP address access to your EC2 instance.

   

7. In the Summary section, review your EC2 configuration and choose Launch instance if correct.Edit security groups.

   

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.

1. On the Amazon EC2 Management Console, under Network and Security, choose Security groups.

   

2. Choose Create security group.

   

3. In the Basic details section:

   1. For Security group name, enter demoDocDB.

   2. For Description, enter a description.

   3. For VPC, accept the usage of your default VPC.

   

4. In the Inbound rules section, choose Add rule.

   1. For Type, choose Custom TCP Rule.

   2. For Port range, enter 27017.

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

   

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

1. Navigate to the Amazon DocumentDB console and choose Clusters from the navigation pane.

   

2. Choose Create.

   

3. Leave the Cluster type setting at it's default of Instance Based Cluster.

   

4. For Number of instances, choose 1. This will minimize cost. Leave the other settings at their default.

   

5. For Connectivity, leave the default setting of Don't connect to an EC2 compute resource.

   

   Note

   Connecting to an EC2 compute resource automatically creates security groups for your EC2 compute resource connection to your cluster. Since you manually created these security groups in the previous step, you should select Don't connect to an EC2 compute resource so as not to create a second set of security groups.

6. For Authentication, enter sign-in credentials. Important: You will need the sign-in credentials to authenticate your cluster in a later step.

   

7. Turn on Show advanced settings.

   

8. In the Network settings section, for Amazon VPC security groups, choose demoDocDB.

   

9. 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:

1. 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 by clicking the instance ID.

   

2. Choose Connect.

   

3. There are four tabbed options for your connection method: Amazon EC2 Instance Connect, Session Manager, SSH client, or EC2 serial console. You must choose one and follow its instructions. When complete, choose Connect.

   

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.

On Amazon Linux

To install the mongo shell on Amazon Linux

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

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

2. When it is complete, install the mongo shell by executing the following command:

   sudo yum install -y mongodb-org-shell

On Ubuntu 18.04

To install the mongo shell on Ubuntu 18.04

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

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

3. Reload the local package database using the following command:

   sudo apt-get update

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

 

On other operating systems

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://truststore.pki.rds.amazonaws.com/global/global-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

1. On the Amazon DocumentDB console, under Clusters, locate your cluster. Choose the cluster you created by clicking the Cluster identifier.

   

2. In the Connectivity and security tab, locate Connect to this cluster with the mongo shell in the Connect box:

   

   Copy the connection string provided and paste it into your terminal.

   Make the following changes to it:

   1. Make sure you have the correct username in the string.

   2. 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 global-bundle.pem --username demoUser --password

3. Press enter in your terminal. You are now be prompted for your password. Enter your password.

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

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

   db.collection.insert({"hello":"DocumentDB"})

2. You get the following output:

   WriteResult({ "nInserted" : 1 })

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

4. You get the following output:

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

5. 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}
               ])
               

6. You get the following output:

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

7. Use the find() command to return all the documents in the profiles collection. Input the following:

   db.profiles.find()

8. You will get an output that will match the data you typed in Step 5.

9. Use a query for a single document using a filter. Input the following:

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

10. You should get back this output:

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

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

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

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

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

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

14. 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:

• Managing Amazon DocumentDB

• Scaling

• Backing up and restoring

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.