DEV Community

Dmitry Romanoff
Dmitry Romanoff

Posted on

Accessing AWS DocumentDB via SSH Tunnel Using Python

#devops #python #database #mongodb

Amazon DocumentDB is a scalable, highly available, and managed document database service that supports MongoDB workloads. If your DocumentDB cluster is running in a private VPC, you typically can't connect to it directly from your local machine.

In this post, I'll walk you through how to connect to AWS DocumentDB securely from your local machine using an SSH tunnel, and then how to interact with it using Python and PyMongo.

✅ What You’ll Learn

  • How to create an SSH tunnel to DocumentDB
  • How to connect to DocumentDB using Python and PyMongo
  • How to inspect or kill a tunnel if needed

1️⃣ Create the SSH Tunnel

Assuming you have a bastion host (jump box) in the same VPC as your DocumentDB cluster, you can set up a tunnel like this:

ssh -i "my-bastion-host-key-pair.pem" \ -L 27017:docdb-dima-1.cluster-xxxxxxxxxxxx.us-east-1.docdb.amazonaws.com:27017 \ ec2-user@YY-YY-YY-YY.compute-1.amazonaws.com \ -N
Enter fullscreen mode Exit fullscreen mode

🧠 What This Does

  • Connects securely to the bastion EC2 instance
  • Forwards port 27017 from your local machine to the DocumentDB cluster endpoint
  • -N means: don’t run a remote command — just establish the tunnel

⏩ Run It in the Background

If you don’t want the SSH tunnel to block your terminal:

ssh -f -i "my-bastion-host-key-pair.pem" \ -L 27017:docdb-dima-1.cluster-xxxxxxxxxxxx.us-east-1.docdb.amazonaws.com:27017 \ ec2-user@YY-YY-YY-YY.compute-1.amazonaws.com \ -N
Enter fullscreen mode Exit fullscreen mode

-f sends the SSH process to the background.

2️⃣ Check if the Tunnel Is Open

You can verify that the local port is listening using lsof:

lsof -P | grep -i "listen" | grep 27017
Enter fullscreen mode Exit fullscreen mode

If it’s open, you’ll see output like this:

ssh 43491 myuser 7u IPv6 0x... TCP localhost:27017 (LISTEN)
Enter fullscreen mode Exit fullscreen mode

3️⃣ Kill the SSH Tunnel

To stop the tunnel manually:

kill -9 <process_id>
Enter fullscreen mode Exit fullscreen mode

Or more dynamically:

lsof -i :27017 | awk 'NR>1 {print $2}' | xargs kill -9
Enter fullscreen mode Exit fullscreen mode

4️⃣ Connect to DocumentDB Using Python

Now that the tunnel is active, you can connect from Python using pymongo.

🐍 Python Code 

from pymongo import MongoClient # Connection details uri = ( "mongodb://myadmin:********@localhost:27017/" "?ssl=true" "&retryWrites=false" "&tlsAllowInvalidHostnames=true" "&replicaSet=rs0" "&readPreference=secondaryPreferred" "&directConnection=true" ) # Path to Amazon DocumentDB CA certificate ca_cert_path = "global-bundle.pem" # Connect to the 'test' database client = MongoClient(uri, tlsCAFile=ca_cert_path) db = client["test"] # List collections collections = db.list_collection_names() print("Collections in 'test':", collections)
Enter fullscreen mode Exit fullscreen mode

🔐 A Note About directConnection=true

Using directConnection=true tells the driver to treat this as a standalone connection — this avoids issues with replica set discovery when you're tunneling only a single instance.

✅ Recap

  • ✅ SSH tunnel lets you connect to a private DocumentDB instance from your local machine
  • ✅ Use mongosh or pymongo with the localhost:27017 endpoint
  • ✅ Add directConnection=true to avoid replica set issues during tunneling

Top comments (0)