Special cases
Cloud SQL for PostgreSQL special cases - IAM authentication done right, cross-cloud tenants, multiple instances and read replicas, and private IPs that quietly change.
IAM authentication done right, cross-cloud tenants, multiple instances and read replicas, and private IPs that quietly change underneath you.
IAM authentication - what UI doesn't tell you
Besides Basic auth (database username/password), the connector supports Google IAM authentication in three flavors. Each has a prerequisite that's easy to miss:
| Method | Works in | Watch out for |
|---|---|---|
| IAM user | Direct + Agent | Uses a short-lived access token (gcloud auth print-access-token, ~1 hour expiry). Fine for a one-off test, wrong for scheduled crawls - the token dies before the next run. |
| IAM service account | Direct + Agent | JSON key based - the right choice for scheduled crawls. Keep the key in a secret store, not in a wiki. |
| Workload Identity Federation | Agent only (runtime on GKE) | No key at all - the GKE service account is impersonated. Not offered in Direct mode; if you can't see it in the UI, that's why. |
Two extra requirements for any IAM method:
-
You need the instance connection name (
my-project:us-central1:my-instance, from the instance's Overview page) in addition to credentials. -
The IAM identity must also be added as a database user on the instance (Cloud SQL → Users → Add user account → Cloud IAM), and granted login. An IAM role alone produces:
FATAL: role "example-sa@example-project.iam" is not permitted to log in
Atlan tenant on AWS/Azure, database on GCP
Private Service Connect needs both ends in Google Cloud, so it's off the table when your tenant runs on AWS or Azure. Your options, in order of preference:
- Self-deployed runtime - works regardless of tenant cloud, since the agent runs in your GCP network and only makes outbound HTTPS calls.
- Public IP + authorized networks - also cloud-agnostic; allowlist your tenant's egress IPs (via support for AWS/Azure tenants).
- Custom cross-cloud design - e.g. an AWS PrivateLink endpoint to a proxy that reaches GCP over your own interconnect. Bespoke: raise a ticket describing both clouds and both regions before designing anything.
If you're moving databases between clouds (or considering re-homing your Atlan tenant), state that in the same ticket - the right connectivity design depends on the end state, not the current one.
Multiple instances, environments, and read replicas
- Each Cloud SQL instance is a separate connection in Atlan, with its own host, credentials, and (for PSC) its own endpoint - endpoints are per-service and can't be shared.
- Crawl a read replica instead of the primary if you want zero crawler load on production - metadata is identical. The replica has its own IP and its own authorized-networks list: allowlist it separately.
- Connecting dev/stage/prod? Do all environments in one support ticket, clearly labeled - it avoids repeated round-trips and mismatched naming.
Private IPs can change out from under you
Managed-database private IPs are not guaranteed stable across certain restarts and maintenance events. If your setup pins the database's IP anywhere - an agent config, a DNS record, a custom hosted zone on the Atlan side - a working connection can break "with no changes on your side".
- Prefer DNS names over raw IPs everywhere a hostname is accepted.
- If a static mapping is unavoidable, document where it lives and who updates it after maintenance.
- Symptom to remember: connection timeouts after a database restart/maintenance window → check whether the private IP moved before touching credentials.