How do I resolve problems connecting to my Amazon DocumentDB cluster?

Short description

Amazon DocumentDB is a VPC-only service and doesn't support public endpoints. As a result, you can't connect directly to an Amazon DocumentDB cluster from an environment outside AWS. You can connect to Amazon DocumentDB using the following methods:

• Connect from an Amazon Elastic Compute Cloud (Amazon EC2) instance that is in the same Amazon Virtual Private Cloud (Amazon VPC). You can also connect from another AWS service (such as AWS Lambda or Amazon SageMaker) that is in the same VPC.
• Connect from an EC2 instance that is in a different VPC by using VPC peering.
• Connect from a machine outside AWS using an SSH tunnel.

Resolution

Connect from an EC2 instance in the same VPC

1.    Create an EC2 instance in the same VPC that you can use SSH to connect to from your source machine.

2.    Confirm that the Amazon DocumentDB cluster's security group has rules that allow connections from the EC2 instance. By default, the security group for the Amazon DocumentDB cluster must allow inbound connections on port 27017.

3.    Connect to your EC2 instance using SSH. See the following example for a Linux instance:

ssh -i "keypairfile.pem" ec2-user@<EC2 DNS endpoint>

4.    Install the mongo shell on EC2 instance, if you haven't already.

5.    Connect to the cluster:

mongo --ssl --host <Cluster endpoint> :27017 --sslCAFile rds-combined-ca-bundle.pem --username <username> --password <password>

MongoDB shell version: 3.2.11

connecting to: <Cluster>:27017/<user>
rs0:PRIMARY>

Connect from an EC2 instance in a different VPC

1.    Create a VPC peering connection from an EC2 instance that is running in a different VPC than the Amazon DocumentDB cluster.

2.    After the peering connection is successful, follow the steps listed under Connect from an EC2 instance in the same VPC.

Connect from a machine outside AWS using an SSH tunnel

1.    Set up an SSH tunnel from your local computer to an EC2 instance that is running in the same VPC as your Amazon DocumentDB cluster. For more information, see Connecting to an Amazon DocumentDB cluster from outside an Amazon VPC.

ssh -i "keypairfile.pem" -L 27017:<cluster endpoint>:27017 ec2-user@<EC2 tunnel endpoint> -N

This allows you to run commands directly to the local host (27017). The commands are then sent to the Amazon DocumentDB cluster. As a best practice, avoid using this method for production environments or if you use the DocumentDB cluster as a replica set for your connections. For more information, see Connecting to Amazon DocumentDB as a replica set.

Troubleshooting

If you're using one of these methods, and you're still having trouble connecting, check the following:

1. The Amazon DocumentDB cluster has at least one instance that is in an available state. If the instances aren't in available states, they can't accept connections.
2. The source you use to connect to the instance is listed as a source that is authorized to access the cluster in your network access control lists (ACLs), local firewalls, and security group rules.
3. The correct DNS name or endpoint is used to connect to the Amazon DocumentDB cluster. For troubleshooting DNS and connectivity issues, see Cannot connect to an Amazon DocumentDB endpoint.
4. The user name and password are entered correctly when you connect to the cluster. If you forgot the password, you can reset the password by modifying the Amazon DocumentDB cluster.
5. The SSL certificate is passed when connecting from a client or an application. By default, TLS configuration is enabled for Amazon DocumentDB clusters. To disable the TLS configuration, create a new custom Amazon DocumentDB cluster parameter group. Set the tls parameter to disabled, and then modify the cluster to use the new cluster parameter group. For more information, see Managing Amazon DocumentDB cluster parameter groups.

Related information

What is VPC peering?