estuary-ssh-tunnels

SSH Tunnel Troubleshooting for Estuary

Quick Checklist

Before deep debugging, verify these common issues:

1. SSH Endpoint format: Must be ssh://user@hostname:port

   • Check for typos, spaces, missing hyphens
   • AWS regions use hyphens: us-west-2 not us-west 2

2. Private key format: Must be RSA PEM format

   • Must start with -----BEGIN RSA PRIVATE KEY-----
   • NOT -----BEGIN OPENSSH PRIVATE KEY----- (OpenSSH format)
   • NOT -----BEGIN PRIVATE KEY----- (PKCS#8 format)
   • Ed25519 and ECDSA keys are not supported — only RSA

3. IP allowlisting: Estuary data plane IPs must be allowed on:

   • Bastion/SSH server security group (port 22)
   • Database security group (from bastion's private IP)
   • Find the IPs for your data plane at Admin → Settings → Data Planes in the Estuary UI
   • Note: data plane IPs can change after infrastructure scaling — re-verify allowlists if a previously working tunnel stops connecting

4. Data plane selection: The user should verify the correct data plane is selected in the Estuary UI when editing the connector. Each data plane has different egress IPs — using the wrong one means the wrong IPs are connecting.

Testing SSH Connectivity

If the quick checklist doesn't resolve the issue, instruct the user to test SSH connectivity from a machine that can reach the bastion host (e.g., their local machine or another server in the same network):

Test SSH connection

ssh -i /path/to/private_key -o StrictHostKeyChecking=no -v user@bastion-host -p 22

A successful connection confirms the key, username, and network path are correct.

Test the tunnel

ssh -i /path/to/private_key -o StrictHostKeyChecking=no \
    -L 3306:database-endpoint:3306 \
    user@bastion-host -N -v &

Then test the database connection through the tunnel (substitute the client and port for the relevant database type — MySQL 3306, PostgreSQL 5432, SQL Server 1433):

Important: The database address used here (and in the connector's address config field) must be the address as seen from the bastion host — not from the user's local machine. If the database is on a private subnet visible to the bastion (e.g., db.internal:5432), use that address.