AWS Database Blog

Amazon DocumentDB Quick Start: Zero Setup with AWS CloudShell

Amazon DocumentDB (with MongoDB compatibility) launched its integration with AWS CloudShell. With this integration, you can now connect to Amazon DocumentDB with a single click on the AWS Management Console without needing to perform any setup. In this post, we show how to connect to and work with Amazon DocumentDB using CloudShell.

Amazon DocumentDB is a fully managed native JSON document database that makes it straightforward and cost-effective for you to operate critical document workloads at virtually any scale without managing infrastructure. It simplifies your architecture through built-in storage and I/O auto scaling, security best practices, continuous backups, and native AWS service integrations.

Amazon DocumentDB supports vector search capabilities, enabling AI and machine learning (ML) workloads through an integration with Amazon SageMaker Canvas, and offers text search for running full-text queries on your documents. As a document database, Amazon DocumentDB provides straightforward storage, querying, and indexing of JSON data.

AWS CloudShell is a browser-based shell that makes it straightforward to securely manage, explore, and interact with your AWS resources, including Amazon DocumentDB, at no additional charge.

Solution overview

This integration will provide you with a preconfigured AWS CloudShell environment that includes the MongoDB shell, Amazon DocumentDB SSL certificates, and the necessary network setup to effortlessly connect to Amazon DocumentDB through the AWS Console.

Prerequisite

To implement the solution, you need to have the following resources set up:

  • An Amazon DocumentDB cluster. You can use an existing Amazon DocumentDB cluster or create a new cluster.
  • Access to Amazon DocumentDB database user credentials.
  • An AWS Identity and Access Management (IAM) user or role with a policy with the following privileges. As a best practice, when creating IAM roles, we recommend that you follow the principle of least privilege.
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cloudshell:*",
                "rds:DescribeDBSubnetGroups",
                "ec2:CreateNetworkInterface",
                "ec2:CreateTags",
                "ec2:CreateNetworkInterfacePermission",
                "rds:Describe*",
                "rds:ListTagsForResource",
                "ec2:DescribeAccountAttributes",
                "ec2:DescribeAvailabilityZones",
                "ec2:DescribeInternetGateways",
                "ec2:DescribeSecurityGroups",
                "ec2:DescribeSubnets",
                "ec2:DescribeVpcAttribute",
                "ec2:DescribeVpcs"
            ],
            "Resource": "*"
        }
    ]
}
JSON

Connect to Amazon DocumentDB through CloudShell

Complete the following steps to connect to Amazon DocumentDB using CloudShell:

  1. On the Amazon DocumentDB console, choose Clusters in the navigation pane.
  2. Select your Amazon DocumentDB cluster and choose Connect to cluster.
  3. Enter a name for the environment (for example, cloudshell-docdb).
  4. Verify the virtual private cloud (VPC) environment details, and choose Create and Run.
  5. (Optional) Copy the displayed MongoDB connection command.

Within a few seconds, your environment will be set up. You will be prompted to enter the password to connect to Amazon DocumentDB.

By default, you will be prompted to provide the admin user credentials. If you want to connect with a different database user, you can modify the command (copied in Step 5) and run it in the session.

Key considerations

CloudShell allows two concurrent environments for Amazon DocumentDB. Within each environment, you can connect to multiple clusters that share the same network configuration.

You can free up a CloudShell environment by choosing to Delete on the Actions menu of the current environment.

Use Amazon DocumentDB IAM authentication with CloudShell

For password-less authentication with Amazon DocumentDB using authentication with IAM, use the legacy MongoDB shell (mongo) rather than mongosh. For this, you need to install mongo in your CloudShell environment. For installation commands, see Install the MongoDB Shell.

Following example demonstrates using a mongo shell to authenticate with Amazon DocumentDB through the MONGODB-AWS mechanism using an Access Key and Secret Key (of IAM user).

$ mongo 'mongodb://<access_key>:<secret_key>@<cluster_endpoint>:<db_port>/test?authSource=%24external&authMechanism=MONGODB-AWS'
Code

Note: The access_key and secret_key must belong to an IAM user who has been configured with appropriate database privileges in the $external database of your Amazon DocumentDB cluster. For detailed instructions, refer to Getting Started with IAM Users and Roles in DocumentDB.

Clean up

If you are no longer using your newly created Amazon DocumentDB cluster, you can stop the cluster or delete the cluster. Cleanup the CloudShell environment created by choosing to Delete on the Actions menu of the current environment. Additionally, if you created a new IAM role and aren’t using it elsewhere, you can delete the role.

Summary

In this post, we demonstrated how to connect to an Amazon DocumentDB cluster through AWS Console using CloudShell. This connection process requires no additional configuration, streamlining your experience of connecting to Amazon DocumentDB.

For more information about recent launches and blog posts, see Amazon DocumentDB (with MongoDB compatibility) resources.

About the author

Kaarthiik Thota is a Senior DocumentDB Specialist Solutions Architect at AWS. He is passionate about database technologies and enjoys helping customers solve problems and modernize applications using NoSQL databases. Before joining AWS, he worked extensively with Relational databases, NoSQL databases, and Business Intelligence (BI) technologies for over 15 years.