For each active database, Tonic Ephemeral provides access to the connection details for the database.
The connection details include the SSH tunnel connection information, and the general connection information for the database. To connect to a database, your Ephemeral account must have an associated public key for the SSH bastion private key. For information on how to add public keys to your account, go to #ephemeral-account-ssh-tokens.
On the Databases page, to display the connection details panel for the database, click the database icon for the database, or select Connection Info from the actions menu.
Each field includes a copy icon to allow you to copy the value to the clipboard.
To create an SSH tunnel to a database from a local machine:
ssh -N -L <localport>:<database-hostname>:<database-port> <bastion-username>@<bastion-host> -p <bastion-port>
For example:
ssh -N -L 9999:svc-bd391f5270d64defb63100cc1bdaa32b:5432 jumper@db.ephemeral.tonic.ai -p 9000
In the command:
-N
tells SSH to not open a shell. Ephemeral does not allow shell access.
<localport>
is the port the database will be accessible at on your local machine.
The other values (<database-hostname>
, <database-port>
, <bastion-username>
, <bastion-host>
, <bastion-port>
) are available from the Connection Info panel.
If the private key file is not configured in your SSH agent, then you can optionally add -i
to specify the private key file.
ssh -N -L <localport>:<database-hostname>:<database-port> <bastion-username>@<bastion-host> -p <bastion-port> -i <private-key-file>
For example:
ssh -N -L 9999:svc-bd391f5270d64defb63100cc1bdaa32b:5432 jumper@db.ephemeral.tonic.ai -p 9000 -i ephemeral-key.pem
To interact with an Ephemeral database programmatically, instead of issuing individual commands to create the SSH tunnel, you can use an SSH sidecar.
In Ephemeral, an SSH sidecar is a Kubernetes sidecar container that creates an SSH tunnel to a remote host through a bastion. It runs alongside other containers in a single pod.
The other containers use the sidecar to connect to an Ephemeral database without having to create the SSH tunnel themselves.
You deploy an SSH sidecar for each database connection.
The image is published at quay.io/tonicai/ephemeral_ssh_sidecar. We recommend that you use the latest
tag.
The private key that is used to authenticate with the SSH host should be mounted to the container as a secret.
To ensure that the SSH client does not reject the key, mount the secret with 0600 file permissions.
Use the following environment variables to configure the sidecar for an Ephemeral database connection.
The SSH host and remote host information for the database is included in the database connection information that is returned by the Ephemeral API. For more information, go to Getting information about Ephemeral databases.
The following variables are used to configure the authentication to the SSH host.
The following settings identify the host and port where the Ephemeral database is located:
The following setting identifies the local port from which to make the connection:
Thee following setting configures the retry behavior for the tunnel creation:
Here is an example of a Kubernetes deployment that uses an SSH sidecar to connect to an Ephemeral database through an SSH tunnel:
When you configure your application to use the sidecar to connect to an Ephemeral database, the connection information is:
Host
- The IP address or hostname of the pod that runs the SSH tunnel image. If it is on the same pod, then Host
is localhost
.
Port
- The value that you configured for LOCAL_PORT
.
Username
and Password
- The values of the Username and Password fields in the Ephemeral database connection information.
SSH_USER
The user that is used to connect to the SSH host.
SSH_HOST
The SSH host for the SSH tunnel.
SSH_PORT
The port on the SSH host.
PRIVATE_KEY_FILE_PATH
The path to the private key file that is used to authenticate with the SSH host.
REMOTE_HOST
The remote host to create the SSH tunnel to. This is the host for the Ephemeral database.
REMOTE_PORT
The port on the remote host.
LOCAL_PORT
The port on the local host from which the SSH tunnel is created.
RETRY_ON_COLLAPSE
Whether the sidecar attempts to recreate a collapsed tunnel.
The default is false
.
Before you set this to true
, make sure that your configuration is correct. If the SSH tunnel collapses because of a misconfiguration, it can start an unending cycle of the tunnel collapsing and the sidecar attempting to recreate it.