Get started with Amazon DocumentDB elastic clusters - Amazon DocumentDB

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

  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 existing policies directly.

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

  7. Click the blue button at the bottom that says Next: Review.

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

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

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

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

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

    
         Diagram: elastic cluster identifier
  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.

    
         Diagram: elastic cluster shard number and capacity
  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).

    
         Diagram: elastic cluster VPC and Subnets
  7. 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.

    
         Diagram: elastic cluster username and password
  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.

    
         Screenshot of the Backup pane showing the steps to configure the cluster backup window.
    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.

    
         Diagram: elastic cluster username and password
  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: 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.

  1. Use your AWS account and access the AWS Management Console.

  2. Navigate to the AWS Cloud9 Console. You can type "Cloud9" in the Search field to locate it.

  3. On the AWS Cloud9 environment home page, choose Create environment.

  4. On the Name environment page, in the Name field, enter a name of your choosing.

    Choose Next step.

    
      Diagram: Cloud9 name
  5. 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).

    
      Diagram: Cloud9 environment settings
  6. Expand Network settings (advanced).

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

    Choose Next step.

    
      Diagram: Cloud9 network settings
  7. 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.

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

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

    
       Diagram: elastic cluster list screen
  2. 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.

    
       Diagram: elastic cluster connect screen
  3. Once connected, you should see the following output:

    
       Diagram: Final elastic cluster connect screen

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 }