SSH Tunneling
SSH tunneling is a networking feature that allows Meroxa to communicate to resources that are not publicly available over the internet.
SSH tunneling cannot be enabled on an existing resource; you must create a new resource.
Requirements
- Create a bastion host
- Whitelist Meroxa IPs on bastion host
- Set up Resource Private Subnet Security Group / Firewall Rule
Configure resource with SSH Tunnel
Use the meroxa resource create command to configure your resource and include the --ssh-url option:
$ meroxa resource create pg_db
--type postgres \
--url postgres://$PG_USER:$PG_PASS@$PG_URL:$PG_PORT/$PG_DB \
--ssh-url ssh://user@[email protected]:22
Resource "pg_db" is successfully created but is pending for validation! Paste the following public key on your host:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC8vC5gN+f1cnYXE5ZTTzijSTVzH/sxA7fMaOY8hIudBNYUBk8dHkj9DQjdz+ecqUltNm/QsMkxCpcg0U279ZLcZ3hTSVfgs3I7aLPV
Meroxa will try to connect to the bastion host for 60 minutes to create a SSH Tunnel and, upon success, will send an email confirmation of resource creation. If still unsuccessful after 60 minutes, the Meroxa Platform will mark the resource state as error and it will not be available for use. You will need to delete the resource, adjust your bastion or resource configuration as needed, and recreate the resource on the Meroxa Platform to try again.
Note that user in the --ssh-url is the user of the bastion host (ec2-user if using the default AWS bastion host setup) and that password is optional, in the case that a password is not needed for ssh access.
Add a public key
In the example above, Meroxa returns a public key which you will need to add to your bastion host to validate the connection to your resource within the 60-minutes time period from creation.
You can do this by adding the public key to ~/.ssh/authorized_keys, where ~ is the home directory for the user on the bastion host. This assumes your bastion host is running Linux - if you are running another operating system such as Windows, add the key respectively according to the OS.
Meroxa will attempt to connect to your resource during that time period and will send a confirmation email after establishing a connection.
To use the same Public and Private Key pair across multiple resources you can simply use the same Private key in each resource and Meroxa will not generate additional Public Keys.
Supply a private key
You can provide the path to a private key for the SSH tunnel by using the --private-key-file string option while creating the resource. One advantage of doing this is that you can utilize the private key with multiple resources while using the same public key on the Bastion host.
Linux / MacOS
To generate a key pair on Linux or MacOS, you can use the ssh-keygen tool from your terminal and follow the prompts.
Windows
To generate a key pair on Windows, verify that you have OpenSSH Client installed. Then, open a command prompt with Administrator priviledges, enter the command ssh-keygen and follow the prompts.
Validate Tunnel Connection
After creating your resource with SSH Tunneling, if you have not added the SSH key to your bastion host within 60 minutes, you will need to validate your resource manually.
$ meroxa resources validate $RESOURCE_NAME
This command is also useful when something changes on your remote server, such as a database password update.
Rotating SSH Keys
In some cases, such as a company policy or a general security practice, you may need to rotate the SSH key used to validate the resource connection.
You can rotate keys with the following command:
$ meroxa resources rotate-tunnel-key $RESOURCE_NAME
The command above will return a new SSH key. Meroxa will attempt to connect to the bastion host for 60 minutes. If unable to connect, you will need to validate the connection again.
When you rotate your key, it will immediately affect the connection to the bastion host, so we recommend that you pause your pipeline before proceeding.
Create a bastion host
To enable SSH Tunneling, you will need a bastion host within your infrastructure.
Here are resources to help you create a host within the various infrastructure providers:
Setup Private Subnet Security Group / Firewall
Ensure that the resource in your private subnet has a Security Group / Firewall rule to allow access from the Bastion Host's security group in the public subnet, matching the port your resource uses. SSH Tunneling on Meroxa works with any cloud provider, but if you're on AWS, you can find your Security Groups here.