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

Short description

To use an SSH tunnel 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

The following resolution 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 through an SSH tunnel.

Prerequisites:

• Create an Amazon DocumentDB cluster.
• Launch an instance with a public IP address in the same Amazon VPC as the Amazon DocumentDB cluster.
• Associate a private key pair (.pem file) with the instance that you downloaded onto 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 the MongoDB Shell or a GUI client on your local machine.

Confirm that the Amazon DocumentDB cluster is accessible from the Amazon EC2 bastion host

Use the private key pair to connect to the bastion host from your local machine through SSH:

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

Note: Replace path_to_pem_file with the path for your .pem key file. Replace instance-user-name with the username for your instance. Replace instance-public-dns-name with your instance public DNS name or IP address.

For more information see Connect to your Linux instance using an SSH client.

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

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

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

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

Note: Replace cluster-endpoint with your DocumentDB cluster endpoint. Replace primary-username with your database primary username. Replace primary-password with your database master password.

For more information, see Connect using Amazon EC2.

Configure the SSH tunnel

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

To set up an SSH tunnel from your local machine to a bastion host, run a command similar to the following example:

ssh -i path_to_pem_file -L local-port:cluster-endpoint:remote-port instance-user-name@instance-public-dns-name -N -f

Note: Replace path_to_pem_file with the path to your EC2 instance private key file. Replace local-port replace with the port number you want to use on your local machine. Replace cluster-endpoint with your DB cluster endpoint. Replace remote-port with the port number of your remote database.

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-aaa-yyy-zzz.compute-1.amazonaws.com -N -f

The following command line options are used in the preceding example command:

• i identity_file, uses the private key-pair for the instance (.pem file) for authentication.
• 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 when you forward ports.
• f, runs the SSH to run in the background.

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

Note: Replace local-port with your port number.

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 preceding command on Windows.

To confirm that the local host listens at local port 27017, run the following command:

nc -zv 127.0.0.1 27017

Review the output. If the SSH tunnel is successfully established, then you see an output similar to the following example:

❯ lsof -P | grep -i "listen" | grep 27017ssh 52787 user 7u IPv4 0x1256bbb543454447 0t0 TCP localhost:27017 (LISTEN)
❯ netstat -abn | findstr "LISTEN" | findstr 27017TCP 127.0.0.1:27017 0.0.0.0:0 LISTENING
❯ nc -zv 127.0.0.1 27017Connection to 127.0.0.1 port 27017 [tcp/*] succeeded!

The preceding example uses port 27017.

Connect to the Amazon DocumentDB cluster from your local machine

Use the MongoDB Shell or a GUI client to connect to the Amazon DocumentDB cluster from your local machine.

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

To use the MongoDB Shell connect to the Amazon DocumentDB cluster, run the following command:

mongo --tls --tlsAllowInvalidHostnames --tlsCAFile global-bundle.pem --username primary-username --password primary-password

Note: Replace primary-username with your database username. Replace primary-password with your database password.

The preceding example command doesn't explicitly specify the --host and --port parameters. When you don't specify the --host and --port parameters, MongoDB Shell tries to connect to your machine's local host at local port 2701. The SSH tunnel then forwards the connection to the Amazon DocumentDB cluster endpoint.

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

Important considerations

Review the following considerations:

• Some GUI clients have an SSH tunnel 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, see the documentation for your specific GUI client.
• When you need to bypass SSL/TLS hostname validation, use the --tlsAllowInvalidHostnames parameter to connect over an SSH tunnel. The hostname 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 you don't need to use the --tlsAllowInvalidHostnames parameter.
• 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 SSL/TLS tab.
• When you use an SSH tunnel 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 might occur. When you use MongoDB Compass for the SSH tunnel, activate Direct Connection to turn off the replica set connection. For more information, see General connection tab on the MongoDB website.

Related Information

Connecting to an Amazon DocumentDB cluster from outside an Amazon VPC

What is MongoDB Compass? on the MongoDB website