SSH tunneling

Connect to a SQL database in your VPC over an SSH tunnel.

If your database is inside a private network, SSH tunneling is one option to allow tasks running on Airplane-hosted agents to connect to your database.

SSH tunneling is typically useful only if you're using Airplane-hosted agents. If you're self-hosting agents, you can deploy agents into a similar network as you would the SSH jump host. Tasks running on those agents could connect to the database behind the VPC without any SSH tunneling, firewall permitting.

In an SSH tunneling setup, you'll typically have:

  • An SSH jump host, accessible from the public Internet. To further secure this, you can whitelist SSH connections from Airplane IP addresses.
  • A user on the host with an associated private key for authentication.
  • Connectivity between the host and your database. The host is usually inside the same network as the database and can connect to the database's private IP address.

Configuring SSH on a database resource

To add SSH tunneling, you'll configure the resource (e.g. a PostgreSQL or MySQL resource) and enable "Connect over SSH."

  • SSH host can be the public IP address of the host, or a DNS record if you have one set up. Make sure you use the public IP, not the private IP (e.g. 10.1.2.3).
  • SSH port is typically 22, unless you've configured it differently.
  • SSH username and SSH private key will need to be configured by you (see below for an example guide). Make sure you use the private key, not the public key.

If you're connecting to a private database, make sure the Host for your database resolves to the private IP address. If you're using Amazon RDS, the instance hostname (e.g. yourdb.xyz.us-east-1.rds.amazonaws.com) will already resolve to the private IP.

Try clicking the "Test connection" button before saving the resource to validate your SSH settings.

Setting up an SSH host

Configuring the SSH host will vary depending on your network setup. If you need further help with, feel free to reach out (support@airplane.dev) and we'll walk you through it!

Typically, you'll want to launch an instance inside your network:

  • It can have minimal CPU and RAM. You'll only need higher resources if it affects network bandwidth.
  • Make sure you launch it in a "public" subnet. It should have a public IP address.
  • It should have network connectivity to your database. If your database is in a different subnet, for example, make sure that the SSH host is in a subnet with the right network ACLs.

If you're using AWS, you can create a keypair ahead of time and launch the instance with the keypair. If you're using Ubuntu, the default user is ubuntu. If you're using Amazon Linux, the default user is ec2-user. You can use this username plus the private key in the keypair to connect.

Once you can connect to the instance, if you'd like you can generate a specific user for Airplane and configure an SSH key:

bash
Copied
1
sudo adduser airplane --disabled-password
2
3
# This generates id_rsa and id_rsa.pub by default
4
# Copy id_rsa for later: this is your private key
5
ssh-keygen -t rsa 4096
6
7
# Add id_rsa.pub to the new user's authorized_keys file:
8
sudo mkdir -p ~airplane/.ssh
9
sudo touch ~airplane/.ssh/authorized_keys
10
sudo chown airplane:airplane ~airplane/.ssh/authorized_keys
11
sudo chmod 644 ~airplane/.ssh/authorized_keys
12
13
cat id_rsa.pub | sudo tee -a ~airplane/.ssh/authorized_keys
14
15
# Delete id_rsa and id_rsa.pub when you're done
16
rm id_rsa id_rsa.pub

Copy id_rsa and use it as the private key in the instructions above.