Connecting to a database

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 Managing SSH tokens.

Getting the connection details

The connection information is on the Connection Details tab of the database details panel.

From the Databases page, to display the connection details for the database:

• Click the database icon for the database.

Connection details icon for a database

• Click the options icon for the database, then click Connection Info.

Actions menu with the Connection Info option

On the Connection Details tab, each field includes a copy icon to allow you to copy the value to the clipboard.

Connection details for an Ephemeral database

Information on the Connection Details tab

Ephemeral Cloud

On Ephemeral Cloud, the database connection is always through an SSH tunnel.

The connection details include:

• Information for the SSH tunnel connection

• Connection information for the database

Self-hosted Ephemeral instance

A self-hosted Ephemeral instance can be configured to either use SSH tunnels or use direct connections on DNS.

If the instance uses SSH tunnels, then the connection details include:

• Information for the SSH tunnel connection

• Connection information for the database

If the instance uses direct DNS connections, then the connection details only include the database connection information.

For information on how to configure the connection type, go to Configuring database access on a self-hosted instance.

Creating an SSH tunnel to a database

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 [e-mail] -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 [e-mail] -p 9000 -i ephemeral-key.pem

Confirming and troubleshooting the SSH tunnel connection

If you are not sure that the connection is successful, or are unable to connect to the database, then here are a couple of troubleshooting steps to check that the tunnel is open and you can connect to the database.

Verifying that the tunnel is open

To verify that the tunnel is open, try to connect in a tool such as telnet or netcat. Test the connection from the same machine that you used when you ran the command to open the tunnel.

For example, to use netcat to try to connect from your local machine:

nc -zv localhost <localPort>

Or for telnet:

telnet localhost <localPort>

If the tool does not return an error, then the tunnel is open.

Verifying that you can connect to the database

After you verify that the tunnel is open, to verify that you can connect to the database, use a terminal client to issue a query against the database.

If the query from the terminal client is successful, but you are unable to connect from your database client, then there might be an issue with your database client.

Using an SSH sidecar to connect to a database

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.

Obtaining the sidecar image

The image is published at quay.io/tonicai/ephemeral_ssh_sidecar. We recommend that you use the latest tag.

Mounting the SSH private key

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.

Configuring the connection details for the sidecar

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.

SSH host connection information

The following variables are used to configure the authentication to the SSH host.

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.

Ephemeral database host and port

The following settings identify the host and port where the Ephemeral database is located:

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 to use from which to create the SSH tunnel

The following setting identifies the local port from which to make the connection:

LOCAL_PORT

The port on the local host from which the SSH tunnel is created.

Other configuration

Thee following setting configures the retry behavior for the tunnel creation:

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.

Example deployment with a sidecar

Here is an example of a Kubernetes deployment that uses an SSH sidecar to connect to an Ephemeral database through an SSH tunnel:

apiVersion: v1
kind: Secret
metadata:
  name: ssh-key-secret
data:
  my-key-name: <base64_encoded_private_key>
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: contact-list-api
  labels:
    app: contact-list
spec:
  replicas: 1
  selector:
    matchLabels:
      app: contact-list
  template:
    metadata:
      labels:
        app: contact-list
    spec:
      containers:
        - name: contact-list-api
          image: contact_list_api:latest
          env:
            - name: CONTACT_LIST_DB_HOST
              value: "localhost"
            - name: CONTACT_LIST_DB_PORT
              value: "12345"
            - name: CONTACT_LIST_DB_USER
              value: "postgres"
            - name: CONTACT_LIST_DB_PASSWORD
              value: "<password>"
            - name: CONTACT_LIST_DB_NAME
              value: "postgres"
        - name: ssh-sidecar
          image: quay.io/tonicai/ephemeral_ssh_sidecar:latest
          volumeMounts:
            - name: ssh-keys
              mountPath: /var/ssh
              readOnly: true
          env:
            - name: SSH_PORT
              value: "9000"
            - name: SSH_HOST
              value: "db.ephemeral.tonic.ai"
            - name: SSH_USER
              value: "jumper"
            - name: REMOTE_PORT
              value: "5432"
            - name: REMOTE_HOST
              value: "svc-ab3a5257f54d49d8b27583af6707646d"
            - name: LOCAL_PORT
              value: "12345"
            - name: PRIVATE_KEY_FILE_PATH
              value: "/var/ssh/my-key-name"
            - name: RETRY_ON_COLLAPSE
              value: "true"
      volumes:
        - name: ssh-keys
          secret:
            secretName: ssh-key-secret
            defaultMode: 0600

Configuring your application to connect with the sidecar

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.