How can I use an SSH tunnel to connect to my Amazon DocumentDB cluster from outside an Amazon VPC?

Short description

To use SSH tunneling to forward the traffic from your local machine to the Amazon DocumentDB cluster, use an Amazon Elastic Compute Cloud (Amazon EC2) instance as a bastion or jump host. The bastion host acts as a proxy that forwards traffic from your local machine to the Amazon DocumentDB cluster.

Resolution

This example uses an EC2 instance as a bastion host. The bastion host uses the MongoDB command line interface (CLI) client to connect to the Amazon DocumentDB cluster from a local machine with SSH tunneling.

Prerequisites:

• Create an Amazon DocumentDB cluster.
• Launch an instance with a public IP address in the same VPC as the Amazon DocumentDB cluster.
• Associate a private key pair (.pem file) with the instance that's downloaded on your local machine.
• Associate a security group with the Amazon DocumentDB cluster. The security group allows communication from the instance over the port that's configured with the Amazon DocumentDB cluster (default 27017).
• Associate a security group with the instance. The security group allows communication from your local machine over SSH port (22).
• Install MongoDB Shell or a GUI client on your local machine.

Verify that the Amazon DocumentDB cluster is accessible from the bastion host

Confirm that the Amazon DocumentDB cluster is accessible from the EC2 bastion host. Connect directly to the bastion hose through SSH, and then use MongoDB Shell to connect to the DB cluster.

1. From your local machine, use the private key pair to connect to the bastion host through SSH. For more information see Connect to your Linux instance from Linux or macOS with SSH.

   ssh -i <path_to_pem_file> <instance-user-name>@<instance-public-dns-name>

2. To authenticate your cluster, download the certificate authority (CA) certificate for Amazon DocumentDB:

   wget https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem

3. Use the MongoDB CLI client to connect to the Amazon DocumentDB cluster:

   mongo --tls --host <cluster-endpoint> --tlsCAFile global-bundle.pem --username <master-username> --password <master-password>

For more information on how to connect to the Amazon DocumentDB cluster from an instance, see Connect using Amazon EC2. To troubleshoot common connection issues, see Connection issues.

Configure the SSH tunnel

After you verify the connection to the cluster from a bastion host, configure the SSH tunneling.

1. To set up an SSH tunnel from your local machine to a bastion host, use a syntax similar to the following one:

   ssh -i <path\_to\_pem\_file> -L <local-port>:<cluster-endpoint>:<remote-port> <instance-user-name>@<instance-public-dns-name> -N -f

   The following command line options are used in this syntax:

   i identity_file - Private key-pair for the instance (.pem file).

   L port:host:hostport - Binds the port on the local (client) host to forward the traffic on the hostport of the remote host.

   N - Doesn't run a remote command. This is useful only for forwarding ports.

   f - Allows SSH to run in the background.

   In the following example, the SSH tunnel binds port 27017 of the local machine to the remote Amazon DocumentDB cluster:

   ssh -i "ec2Access.pem" -L 27017:sample-cluster.node.us-east-1.docdb.amazonaws.com:27017 ec2-user@ec2-zz-xxx-yyy-zzz.compute-1.amazonaws.com -N -f

2. To verify that the SSH tunnel runs in the background, run a command similar to the following one:

   Linux and macOS:

   lsof -P | grep -i "listen" | grep <local-port> 

   Windows:

   netstat -abn | findstr "LISTEN" | findstr <local-port>

   Note: You must be an admin user to run the Windows command.

3. To confirm that the local host listens on local port 27017, run the following command:

   nc -zv 127.0.0.1 27017

4. Review the output. If the SSH tunnel is successfully established, then you see an output similar to the following one. This example assumes that port 27017 is used:

   ❯ lsof -P | grep -i "listen" | grep 27017
   ssh 52787 user 7u IPv4 0x1256bbb543454447 0t0 TCP localhost:27017 (LISTEN)

   ❯ netstat -abn | findstr "LISTEN" | findstr 27017
   TCP 127.0.0.1:27017 0.0.0.0:0 LISTENING

   ❯ nc -zv 127.0.0.1 27017
   Connection to 127.0.0.1 port 27017 [tcp/*] succeeded!

Connect to the Amazon DocumentDB cluster from your local machine

Use MongoDB Shell or any GUI client to connect to the Amazon DocumentDB cluster from your local machine. The hostname that you use in the connection string is the local host, and the port is the local port that's configured in the SSH tunnel.

Note: Before you initiate the connection, download the CA certificate for Amazon DocumentDB on your local machine.

The following example command doesn't explicitly specify the --host and --port parameters. MongoDB Shell tries to connect to the local host of your machine on local port 27017. Then, the connection is forwarded to the Amazon DocumentDB cluster endpoint over the SSH tunnel.

mongo --tls --tlsAllowInvalidHostnames --tlsCAFile global-bundle.pem --username <master-username> --password <master-password>

If you use a custom port other than 27017 on the local machine, then use the --port parameter to explicitly pass the port. For more information, see Connect to a deployment on a remote host on the MongoDB website.

Important considerations

Important:

• Some GUI clients have an SSH tunneling option, such as MongoDB Compass or Studio 3T. When you use these clients, you don't need to manually create and manage the SSH tunnel with the MongoDB CLI. Instead, save the SSH tunnel configuration in the connection settings of the GUI client. For more information, refer to the documentation for your specific GUI client.
• To bypass TLS/SSL hostname validation, use the --tlsAllowInvalidHostnames parameter to connect over an SSH tunnel. The hostname that's used in the connection string, mongodb://localhost:27017, doesn't match the hostname that's in the Amazon DocumentDB cluster server certificate. If you connect directly to the cluster with an Amazon DocumentDB cluster endpoint, then this parameter isn't required.
• For GUI clients such as MongoDB Compass and Studio 3T, specify the tlsAllowInvalidHostnames option in the connection string, tlsAllowInvalidHostnames=true. Or, activate the **Allow Invalid Hostnames** option in the connection settings in the TLS/SSL tab.
• When you use SSH tunneling to connect, it's a best practice to connect to the cluster endpoint. If you specify replicaSet=rs0 in your connection string, then an error can occur. When you use MongoDB Compass for the SSH tunnel, activate Direct Connection to turn off the replica set connection. For more information, see Turn on Direct Connection on the MongoDB website.

Related Information

Connecting to an Amazon DocumentDB cluster from outside an Amazon VPC

MongoDB Compass on the MongoDB website