Configure SSH tunnels

SSH tunnels provide secure connections to databases through bastion hosts. Use them when your database is in a private network that can't be accessed directly from an Ascend Environment.

When to use SSH tunnels

Use SSH tunnels when:

• Your database is in a private VPC or subnet
• Network security policies require connections through a jump host
• You need to access on-premises databases from Ascend

SSH tunnel structure

SSH tunnels are defined in the ssh_tunnels/ directory of your Project:

my_project/
├── ssh_tunnels/
│   └── bastion.yaml
└── connections/
    └── mysql_db.yaml

Create an SSH tunnel

Using password authentication

ssh_tunnels/bastion.yaml

ssh_tunnel:
  host: bastion.example.com
  port: 22
  user: bastionuser
  password: ${vaults.secrets.bastion_password}

Using private key authentication

ssh_tunnels/secure_bastion.yaml

ssh_tunnel:
  host: bastion.example.com
  port: 22
  user: ubuntu
  private_key: ${vaults.secrets.bastion_private_key}

Using passphrase-protected private key

ssh_tunnels/encrypted_bastion.yaml

ssh_tunnel:
  host: bastion.example.com
  port: 22
  user: admin
  private_key: ${vaults.secrets.encrypted_key}
  private_key_passphrase: ${vaults.secrets.key_passphrase}

Configuration reference

Field	Required	Description
host	Yes	Bastion host address or IP
port	Yes	SSH port (typically 22)
user	Yes	SSH username
password	No*	Password for authentication
private_key	No*	Private key content (PEM format)
private_key_passphrase	No	Passphrase for encrypted private key

* Specify exactly one of password or private_key.

Use SSH tunnels in Connections

Reference SSH tunnels by name in your Connection configurations using the ssh_tunnel field.

MySQL

connections/mysql_db.yaml

connection:
  mysql:
    host: internal.db.host
    port: 3306
    database: mydb
    user: dbuser
    password: ${vaults.secrets.db_password}
  ssh_tunnel: bastion

PostgreSQL

connections/postgres_db.yaml

connection:
  postgres:
    host: 10.0.0.50
    port: 5432
    database: analytics
    user: readonly
    password: ${vaults.secrets.pg_password}
  ssh_tunnel: secure_bastion

Microsoft SQL Server

connections/mssql_db.yaml

connection:
  mssql:
    host: 192.168.1.100
    port: 1433
    database: reports
    user: sa
    password: ${vaults.secrets.mssql_password}
    driver: "ODBC Driver 18 for SQL Server"
    trust_server_certificate: true
  ssh_tunnel: secure_bastion

Oracle

connections/oracle_db.yaml

connection:
  oracle:
    host: oracle.internal
    port: 1521
    user: hr
    password: ${vaults.secrets.oracle_password}
    service_name: ORCL
  ssh_tunnel: bastion

Store credentials securely

Always store sensitive values in Vaults:

1. Passwords: Store SSH passwords in a Vault
2. Private keys: Store the full PEM content including headers (-----BEGIN RSA PRIVATE KEY-----)
3. Passphrases: Store key passphrases separately from the key itself

Example Vault reference:

password: ${vaults.my_vault.bastion_password}
private_key: ${vaults.my_vault.ssh_private_key}

Best practices

1. Use private key authentication: More secure than password authentication
2. Minimize bastion exposure: Use private keys with passphrases for additional security
3. Share tunnels: Multiple Connections can reference the same SSH tunnel
4. Use descriptive names: Name tunnels based on their purpose or target environment
5. Rotate credentials: Periodically rotate SSH passwords and keys

Troubleshooting

Issue	Cause	Solution
Connection refused	Bastion not reachable	Verify host address and port
Authentication failed	Wrong credentials	Check username, password, or private key
Permission denied	Key not authorized	Ensure public key is in bastion's authorized_keys
Timeout	Network/firewall issue	Check firewall rules between Ascend and bastion

Supported databases

SSH tunnels work with these Connection types:

• Microsoft SQL Server (MSSQL)
• MotherDuck
• MySQL
• Oracle
• PostgreSQL

Next steps

• Set up database Connections
• Configure Vaults for secure credential storage