Connecting to a database

Getting the connection details

For each active database, Tonic Ephemeral provides access to the connection details for the database.

The connection details include both the general connection information for the database, and the SSH bastion connection information. 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.

On the Databases page, to display the connection details panel for the database, click the database icon for the database.

Connection details for an Ephemeral database

Each field includes a copy icon to allow you to copy the value to the clipboard.

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

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.