Network Requirements

When you connect a data source — a Postgres database, an HTTP API, a warehouse — the onprem deployment itself is the client that opens the connection. The data source must therefore be reachable from the deployment's network, not from your laptop. A connection that works from your machine can still fail from the cluster.

This is the single most common first-connection failure, and it is invisible: a firewall that silently drops packets looks identical to a slow database. If a connection test hangs and then reports a timeout, suspect network reachability before credentials.

The intra-VPC case (usually fine)

If the data source lives in the same VPC / network as the deployment — e.g. an RDS instance or a Cloud SQL database in the same project, peered network, or subnet — it is normally reachable with no extra configuration. Internal traffic stays inside the VPC and is not subject to public-internet firewalls.

You may still need to:

allow the database's security group / firewall to accept traffic from the deployment's subnet or pod CIDR, and
ensure the database listens on an address routable from the cluster (a private IP, not only localhost).

This is the recommended topology: no public exposure, lowest latency.

The cross-network case (allowlisting required)

If the data source is outside the deployment's network — a managed database in a different cloud account, an on-prem database reached over the internet, a third-party API — the deployment's outbound traffic must be permitted to reach it.

Egress IP

The deployment connects out from one or more egress IP addresses (the NAT gateway / load balancer IP of the cluster). The data source's firewall must allowlist these IPs.

On Definite-hosted deployments the egress IP is a reserved static address, shown in Settings → Workspace → General (and as a hint when setting up a database integration). It is safe to allowlist permanently — it is reserved for your deployment alone and survives cluster upgrades.

On self-hosted installs, find the egress IP by running, from inside the deployment, an outbound request to an IP-echo service, or by reading it from your cloud provider's NAT gateway configuration. Treat it as stable but not permanent — re-check it if you rebuild networking. To surface it in Settings the same way hosted deployments do, set the deployment.egressIp Helm value (comma-separated if several).

Firewall / security-group allowlisting

On the data source side, add an inbound rule that allows the deployment's egress IP(s) to reach the database port (Postgres defaults to 5432). Without this rule the connection attempt is dropped and surfaces as a timeout.

VPC peering / private connectivity

For production, prefer VPC peering, a private link, or a VPN over public-internet allowlisting:

no database port is exposed to the internet,
traffic uses private IPs, and
you avoid maintaining IP allowlists as egress IPs change.

Once peered, the connection behaves like the intra-VPC case above.

SSH bastion / jump host

If the database is only reachable through an SSH bastion (a jump host with network access to the database, but the database itself is not directly routable), use the Postgres integration's SSH tunnel fields:

Field	Notes
`ssh_host`	Bastion hostname. Setting this enables the tunnel.
`ssh_port`	Bastion SSH port. Defaults to `22`.
`ssh_user`	SSH login user on the bastion. Required when `ssh_host` is set.
`ssh_private_key`	PEM-encoded SSH private key. Required when `ssh_host` is set. Stored encrypted.
`ssh_key_passphrase`	Optional passphrase if the private key is encrypted.

When configured, the deployment opens an SSH local port-forward to the bastion and connects to the database through it. The bastion must allowlist the deployment's egress IP on its SSH port; the database only needs to be reachable from the bastion.

Leave all SSH fields blank for directly reachable databases — the tunnel is opened only when ssh_host is set.

TLS / SSL to the database

For sslmode=verify-ca or verify-full against a database that uses a private certificate authority, paste the CA certificate (and, for mutual TLS, the client certificate and key) into the Postgres integration's sslrootcert / sslcert / sslkey fields. These are PEM contents, not file paths; the deployment writes them to short-lived private temp files for the duration of each connection. They have no bearing on network reachability — a verify-full connection still needs the firewall rules above.

Checklist when a connection fails

Timeout / "could not connect" → network reachability. Check the data source's firewall / security group allowlists the deployment's egress IP, or that intra-VPC routing and security groups permit the cluster's subnet. If access is via a bastion, set the SSH tunnel fields.
"could not translate host name" / DNS error → the hostname does not resolve from inside the cluster. Use an IP or a name resolvable by the deployment's DNS.
Authentication / permission errors → the connection succeeded; the problem is credentials or grants, not the network.
TLS / certificate errors → the connection reached the database but certificate verification failed. Check sslmode and the sslrootcert / sslcert / sslkey fields.