Connect a private-IP instance via self-deployed runtime
Keep your Cloud SQL for PostgreSQL instance private - run a small Atlan-provided agent inside your network that reads metadata locally and sends it to Atlan over outbound HTTPS only.
Your Cloud SQL instance keeps its private IP and zero internet exposure. You run a small Atlan-provided agent inside your network; it reads metadata locally and sends it to Atlan over outbound HTTPS only. Five phases.
Your instance shows Private IP only under Connections → Networking, and enabling a public IP is off the table. This is the most common private setup for Cloud SQL - and entering that private IP into Direct mode is the most common way it goes wrong (see troubleshooting).
Five phases at glance
| Phase | What happens | Owner | Typical time |
|---|---|---|---|
| 1. Plan | Pick where the runtime runs; open outbound HTTPS | Your infrastructure team | Half a day |
| 2. Install | Deploy the runtime; register it with your tenant | Your infrastructure team | Half a day–1 day |
| 3. Secrets | Store DB credentials in your secret manager; wire it up | Your infrastructure team | 1–2 hours |
| 4. Connect | Create the connection with the agent selected; test | Atlan User | 30 minutes |
| 5. Verify | Confirm runs execute on the agent, not a dead queue | Atlan User | 30 minutes |
Phase 1 - Plan deployment
Owner: Your infrastructure team
- The runtime must run somewhere that can reach the instance's private IP on port 5432 - same VPC, or a peered one. A GKE cluster in the same project is typical.
- Your egress firewall/proxy must allow the runtime's outbound HTTPS (port 443) to your Atlan tenant (e.g.
tenant.atlan.com) and its registration endpoints. If your environment forces an HTTP proxy, the runtime - and any containers it spawns - needs the proxy settings; a missing proxy on spawned containers is a known failure mode. - Follow the platform docs: Configure workflow execution (self-deployed runtime section).
Phase 2 - Install and register runtime
Owner: Your infrastructure team
Install per the self-deployed runtime docs, then confirm the agent shows as healthy/online in Atlan before proceeding. If the agent starts but crawls never begin, check the agent pod logs for authentication errors such as:
ATLAN-CLIENT-401-03: invalid_client
# the agent's client credential is wrong or expired - re-register the agent / refresh the credential
Phase 3 - Configure secret store
Owner: Your infrastructure team
The runtime reads database credentials from your secret manager at run time - they are never uploaded to Atlan. When the workflow setup asks for a Key Type:
"Key Type" describes how the secret is laid out, not which store you use. GCP Secret Manager stores one value per secret, so choose Single Key and create one secret entry per credential field. (Multi Key is for stores like Vault where one secret holds several fields.)
Phase 4 - Create connection
Owner: Atlan User
- Open New workflow → Cloud SQL for PostgreSQL Assets and switch the extraction method from Direct to Self-Deployed Runtime (Agent), then select your agent.
- Enter the instance's private IP (or private DNS name) as the Host - in agent mode this is correct, because the agent resolves it from inside your network.
- Pick the auth method. All four work in agent mode: Basic, IAM user, IAM service account, and Workload Identity Federation (GKE-only, and only available in agent mode).
- Click Test connection.
Phase 5 - Verify runs actually execute on the agent
Owner: Atlan User
A misrouted connection doesn't fail loudly - it hangs. If the workflow template points at a wrong or retired agent queue, runs sit idle until a ~24-hour timeout, and can even surface as "succeeded" with no assets.
- The first run starts doing work within minutes - visible activity in the run logs, not a silent queue wait
- Run duration is in line with your schema size (minutes-to-hours, not "exactly 24 hours")
- Assets appear in Atlan after the run - a "successful" run with zero new assets is a red flag
- After any agent migration or rename, re-check every connection that used the old agent - templates don't repoint themselves
Next steps
Crawl Cloud SQL for PostgreSQL: Configure and run the crawler to extract metadata from Cloud SQL